Add llms.txt for LLM-friendly documentation

next-env.d.ts

@@ -1,6 +1,5 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-/// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.
+// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.

package.json

@@ -8,7 +8,8 @@
 	},
 	"scripts": {
 		"dev": "next dev",
-		"build": "next build",
+		"build": "pnpm generate:llms && next build",
+		"generate:llms": "npx tsx scripts/generate-llms.ts",
 		"start": "next start",
 		"prettier": "prettier --write .",
 		"typecheck": "tsc --noEmit",
@@ -74,6 +75,9 @@
 		"husky": "^9.1.6",
 		"prettier": "^3.3.3",
 		"pretty-quick": "^4.0.0",
+		"remark-mdx": "^3.1.1",
+		"remark-parse": "^11.0.0",
+		"remark-stringify": "^11.0.0",
 		"sucrase": "3.29.0",
 		"typescript": "^5.5.4"
 	},

public/llms-output/colors/aliasing.md

@@ -0,0 +1,54 @@
+# Aliasing
+
+How to use Radix Colors.
+
+# Aliasing
+
+A guide to providing semantic aliases for colors.
+
+## Semantic aliases
+
+Referencing color scales by their actual scale name can work well, like `blue` and `red`. But often, creating semantic aliases like `accent`, `primary`, `neutral`, or `brand` can be helpful, especially when it comes to theming.
+
+With this approach, you will likely run into issues where you need to use the same scale for multiple semantics. Common examples include:
+
+- If you map `yellow` to "warning", you might also need `yellow` to communicate "pending".
+- If you map `red` to "danger", you might also need `red` to communicate "error" or "rejected".
+- If you map `green` to "success", you might also need `green` to communicate "valid".
+- If you map `blue` to "accent", you might also need `blue` to communicate "info".
+
+In this scenario, you can choose to define multiple semantic aliases which map to the same scale.
+
+Or you can simply recommend that your teammates defer to the original scale name for situations where there is no appropriate semantic alias.
+
+## Use case aliases
+
+Each step in Radix Colors scales is designed for a specific use case. To help your team know which step to use, you can provide aliases based on the designed use cases.
+
+Again, with this approach, you will likely run into issues where you need to use the same step for multiple use cases. Common examples include:
+
+- Step 9 is designed for solid backgrounds, but it also may work for input placeholder text.
+- Step 8 is designed for hovered component borders, but it also works well for focus rings.
+
+In these cases, you can choose to define multiple aliases which map to the same step.
+
+Or you can simply recommend that your teammates defer to the original step number for situations where use cases don't have an alias.
+
+## Mutable aliases
+
+When designing for both light and dark modes, you sometimes need to map a variable to one color in light mode, and another color in dark mode. Common examples include:
+
+- Components that have a white background in light mode and a subtle gray background in dark mode. For example, Card, Popover, DropdownMenu, HoverCard, Dialog etc.
+- Components that have a transparent black background in light mode and a transparent white background in dark mode. For example, Tooltip.
+- Shadows that are saturated, transparent gray in light mode, and pure black in dark mode.
+- An overlay that is light transparent black in light mode, and a darker transparent black in dark mode.
+
+Avoid using specific variable names like "CardBg", or "Tooltip", because you will likely need to use each variable for multiple use cases.
+
+## Renaming scales
+
+If you wish, you can rename scales. Reasons might include:
+
+- Rename a saturated gray to `gray` to keep things simple.
+- Rename `sky` or `grass` to `blue` or `green` to keep the naming intuitive.
+- Rename a scale to match your brand, like how Discord use `blurple`.

public/llms-output/colors/composing-a-palette.md

@@ -0,0 +1,65 @@
+# Composing a color palette
+
+A guide to composing a color palette with Radix Colors.
+
+# Composing a color palette
+
+A guide to composing a color palette with Radix Colors.
+
+## Choosing a brand scale
+
+Radix provides a number of scales you could use for your brand or accent color.
+
+Scales designed for white foreground text:
+
+### Custom brand colors
+
+Radix Colors are not intended to be customised. They’re designed to be accessible, well-balanced, and harmonious. Any customisation would likely break these features.
+
+If you need custom brand colors, we recommend adding custom scales alongside Radix scales.
+
+For example, you could use Radix Colors for your gray scale and your semantic scales, then add custom brand/accent colors.
+
+## Choosing a gray scale
+
+Radix Colors provides a pure gray and a few tinted gray scales.
+
+- `gray` is pure gray
+- `mauve` is based on a purple hue
+- `slate` is based on a blue hue
+- `sage` is based on a green hue
+- `olive` is based on a lime hue
+- `sand` is based on a yellow hue
+
+### Neutral pairing
+
+If you want a neutral vibe, or you want to keep things simple, `gray` will work well with any hue or palette.
+
+### Natural pairing
+
+Alternatively, choose the gray scale which is saturated with the hue closest to your accent hue. The difference is subtle, but this will create a more colorful and harmonius vibe.
+
+## Choosing semantic scales
+
+For most projects, you will need colors to communicate semantic meaning. Here are some common pairings that work well in Western culture.
+
+- **Error**: `red`, `ruby`, `tomato`, `crimson`
+- **Success**: `green`, `teal`, `jade`, `grass`, `mint`
+- **Warning**: `yellow`, `amber`, `orange`
+- **Info**: `blue`, `indigo`, `sky`, `cyan`
+
+In many cases, you might eventually need most of the scales, for one reason or another. Your app may support multiplayer mode, where you assign a color to each user. Your app may have a labelling feature, where your users assign a color to a task. Your app may use badges to communicate “pending” or “rejected” states.
+
+Radix Colors are well-balanced, and designed to work in harmony. So for product communication, most color pairings will work.
+
+## Choosing text scales
+
+Steps 11 and 12 are designed for low-contrast text and high-contrast text respectively. Depending on the vibe you want, you can use your accent scale or your gray scale.
+
+Using your accent scale will result in a more colorful vibe.
+
+Using your gray scale will result in a more functional vibe.
+
+The difference may seem subtle, but it can make a huge difference with a whole page of text.
+
+You may want to experiment with using your accent scale for text in your marketing sites, and your gray scale for text in your apps.

public/llms-output/colors/custom-palettes.md

@@ -0,0 +1,31 @@
+# Custom palettes
+
+How to create custom Radix Colors palettes.
+
+# Custom palettes
+
+Learn how to create custom Radix Colors palettes.
+
+Use the [custom color palette tool](/colors/custom) to generate a Radix Colors scale based just on a couple reference colors. Once you are happy with the result, paste the generated CSS into your project and use them the same way you would use the regular Radix Colors scales.
+
+The generated scales are based on the Radix Colors scales themselves, so they will work well with similar component designs. As long as you use a reasonable background color, the contrast ratios will be similar to what Radix Colors provide.
+
+## What you get
+
+Your custom color palette will include Radix Colors steps 1 through 12, as well as their alpha variants and wide-gamut color definitions. Wide-gamut color definitions are needed to ensure that alpha colors are displayed with full saturation in wide-gamut color spaces, such as on Apple’s displays that support P3. This is because alpha blending works differently in P3 than in sRGB.
+
+Learn about the base palette composition in the [Understanding the scale](/colors/docs/palette-composition/understanding-the-scale) guide. The generated CSS also includes a few extra colors used exclusively in [Radix Themes](/themes/docs), such as:
+
+- Surface color, used by certain `variant="surface"` components
+- Indicator color, used by components like Checkbox, Radio, and Tabs
+- Track color, used by components like Slider and Progress Bar
+
+Feel free to remove colors from the generated CSS that you don’t need.
+
+## Color formats
+
+You can use any common CSS color format in the input fields, or even wide-gamut color spaces, such as `color(display-p3 1 0.5 0)`. The generated CSS will provide the closest sRGB fallbacks.
+
+## Dark theme
+
+To generate dark theme colors, toggle the appearance to dark in the website header. Make sure to paste the generated CSS after your light theme color overrides.

public/llms-output/colors/installation.md

@@ -0,0 +1,73 @@
+# Installation
+
+How to install Radix Colors.
+
+# Installation
+
+How to install Radix Colors.
+
+## npm
+
+Install Radix Colors from your terminal via npm, yarn or pnpm. Current version is `3.0.0`
+
+```bash
+# with npm
+npm install @radix-ui/colors
+# with yarn
+yarn add @radix-ui/colors
+# with pnpm
+pnpm add @radix-ui/colors
+```
+
+## CDN
+
+To get started quickly, you can use the CDN files.
+
+```html
+<!-- Load whichever light and dark scales you need -->
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/gray.css"
+/>
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/blue.css"
+/>
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/green.css"
+/>
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/red.css"
+/>
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/gray-dark.css"
+/>
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/blue-dark.css"
+/>
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/green-dark.css"
+/>
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@latest/red-dark.css"
+/>
+```
+
+The example above uses the `@latest` tag to point to the latest version of the scales. You can pin your scales to a specific version.
+
+```html
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@3.0.0/blue.css"
+/>
+<link
+	rel="stylesheet"
+	href="https://cdn.jsdelivr.net/npm/@radix-ui/colors@3.0.0/blue-dark.css"
+/>
+```

public/llms-output/colors/releases.md

@@ -0,0 +1,52 @@
+# Releases
+
+Radix Colors changelog.
+
+# Releases
+
+Radix Colors releases and changelog.
+
+## 3.0.0
+
+
+
+- \[**Breaking**] A complete rework of all colors.
+- Add P3 colorspace versions of all scales.
+
+## 2.1.0
+
+
+
+- Add `ruby`, `iris`, and `jade` scales
+
+## 2.0.1
+
+
+
+- Fix some of the dark `a2` colors being too opaque.
+
+## 2.0.0
+
+
+
+- \[**Breaking**] A complete rework of all colors, dramatically improving contrast across the board.
+
+## 1.0.0
+
+
+
+- \[**Breaking**] CSS variables were changed to use the hyphen-separated naming:
+  - `gray1` → `gray-1`
+  - `grayA1` → `gray-a1`
+- \[**Breaking**] CSS file names were changed to use the hyphen-separated naming:
+  - `gray.css` → `gray.css`
+  - `grayA.css` → `gray-alpha.css`
+  - `grayDark.css` → `gray-dark.css`
+  - `grayDarkA.css` → `gray-dark-alpha.css`
+
+## 0.1.9
+
+
+
+- Apply light scale CSS variables to `.light-theme` class in addition to
+  the `:root` element.