Write design system guidelines for Make kits

When using a Make kit in Figma Make, it’s critical to craft great guidelines.

Authoring guidelines for a Make kit is similar to authoring the documentation you'd give a new engineer at your company to teach them how to properly use the design system. And if you have existing design system documentation or a Storybook, you have the content you need to author guidelines!

To make it even easier, Figma Make can read your design package and create guidelines for you when you’re assembling your Make kit. This removes the big lift with initially authoring guidelines. Learn more in Get started with Make kits.

Whether you choose to generate guidelines or you want to build your own, we provide some best practices that you can apply.

Important considerations

Here are a few important considerations to keep in mind:

• It’s good to have subfolders. The structure of your guidelines helps Figma Make organize its thinking. Organize guidelines into folders based on what the files describe and how they should be used. See Guidelines structure
• Frame your guidelines to describe “what” and “how”. The content of your guidelines files should be clear and precise, a balance of “here’s what this is” and “here’s how you use it”. It’s good to be granular in your approach. See Guidelines content
• Multiple short guidelines files are better than a few large files. Build your guidelines with progressive disclosure and the size of the context window in mind.

Many short files for specific areas of the design system are better than a small number of lengthy guidelines. Include overview files that route Figma Make to more specific guidelines. This helps Figma Make find only what it needs to be successful while not flooding its context window. See Overview guidelines

Guidelines structure

Every Figma Make file has a guidelines/ folder, but Make kits provide even more opportunity to create granular guidelines for your design package. You also add new folders and guideline files to your Make kit, which for documenting specific components or sets of design tokens.

When you create a Make kit with a design package, here are the initial places guidelines files appear:

├── guidelines/
│   ├── components/
│   ├── Guidelines.md
│   ├── setup.md
│   ├── styles.md
│   └── tokens.md
├── src/
│   ├── [your application code here]
├── package.json
├── ATTRIBUTIONS.md
├── postcss.config.mjs
└── vite.config.ts

When you’re done creating guidelines, though, especially granular guidelines for your tokens and components, your Make kit may look a little more like this:

├── guidelines/
│   ├── components/
|      ├── button.md
|      ├── icons.md
|      ├── navigation.md
|      ├── overview.md
|      └── tabs.md
│   ├── composition/
|      ├── hierarchy.md
|      ├── icons.md
|      ├── layout.md
|      ├── overview.md
|      └── surfaces.md
├── foundations/
|      ├── color.md
|      ├── icons.md
|      ├── modes.md
|      ├── spacing.md
|      └── input_styling.md
│   ├── icon-discovery.md
│   ├── setup.md
│   └── overview.md
├── src/
│   ├── [your application code here]
├── package.json
├── ATTRIBUTIONS.md
├── postcss.config.mjs
└── vite.config.ts

The above file structure is just an example to give you inspiration. You may find you want even more granular guidelines. You might also prefer a simpler approach. What’s important is finding the balance that gets you reliable, high quality outcomes.

Note some important qualities about the example file structure:

• Guidelines files are arranged in folders that correspond to the parts of the design system, such as the components and foundation styles.
• Multiple overview guidelines are provided. This lets you provide additional, focused guidance for those parts of your design system.
• Setup and overview guidelines files appear at the root of the guidelines folder structure. These are used to route Figma Make to the appropriate granular files and give a broad overview of how each folder is used.

Guidelines content

When writing guidelines for Figma Make, use clear, concise language: "Do not use small text for anything except captions" is better than "Use small text sparingly". Be specific and imperative in your instructions.

Guidelines.md: top-level guidelines

Guidelines.md is the initial set of guidelines that Figma Make always looks at first. You can change the name of this file to better suit the needs of your design system. For example, the earlier file structure changes the file name to overview.md.

This file is a good place to introduce your design system and give Figma Make a sense of the available components and tokens. It should also explain to Figma Make the other guidelines files that exist and when they should be used.

You shouldn’t use the top-level guidelines file to capture everything about your design system. Instead, use it as an opportunity to give Figma Make a high-level introduction to your design system, and then link out to additional, more granular overview files.

Example: Guidelines.md

# Astra UI Design System Guidelines

## Product character

This is a **B2C SaaS** product with a **minimal, clean, simple** UI style.

- **Density**: Breathable — generous whitespace, compact but not cramped
- **Surface strategy**: Layered — branded `brand-tertiary` canvas with `surface-bg` cards floating on top. Surface color creates hierarchy, not borders.
- **Color palette**: ~90% neutral surfaces. Brand color (`brand-primary`) is used sparingly for primary actions, active states, and small accents only. The `brand-tertiary` lavender canvas provides ambient identity.
- **Corner style**: Rounded (`corner-md` 8px default, `corner-lg` 16px for cards/overlays, `corner-full` for buttons/avatars)
- **Elevation**: Surface-color-driven — shadows reserved for floating overlays (toolbar, modal) only

## Reading order

**MUST READ before writing any code:**
1. This file (`overview.md`) — product character, rules, and workflows
2. `setup.md` — providers, CSS imports, build configuration
3. `foundations/` — all token files (color, typography, spacing, surfaces)
4. `components/overview.md` — full component catalog with alternative names

**Read on-demand:**
- `components/{name}.md` — read BEFORE using that component
- `composition/` — read when building page layouts or combining components

## Workflows

### Before using a component
1. Check `components/overview.md` for the component catalog
2. Read `components/{name}.md` for the specific component
3. Follow all rules, valid props, and usage notes in the guidelines file
4. Do NOT write code using a component until you have read its guidelines file

### Before using an icon
1. Check `icon-discovery.md` for available icons
2. Do NOT guess icon names — verify the icon exists first
3. If an icon doesn't exist, pick a different one and verify
4. Icons are ALWAYS imported from `lucide-react`, never from `@brettmcm/astraui`

### When building a layout
1. Read `composition/layouts.md` for page structure patterns
2. Read `composition/surfaces.md` for layering and background rules
3. Start with `SidebarNavigation` — every desktop page includes it
4. Apply spacing tokens — never hardcode pixel values
5. Use `brand-tertiary` as the page canvas, `surface-bg` for elevated content

## Rules

IMPORTANT: Every desktop page MUST include `SidebarNavigation` — the 60px dark icon rail on the far left. No exceptions.

IMPORTANT: The page background is ALWAYS `brand-tertiary`. Never use white or gray as the page canvas. Content cards use `surface-bg` and float on top.

IMPORTANT: Do NOT use `brand-primary` or `brand-secondary` as backgrounds for large areas — they are for small accents and interactive highlights only.

- Always use design system components over raw HTML elements (`InputField` not `<input>`, `SelectField` not `<select>`)
- All spacing must use design system tokens (`gap-xl`, `p-2xl`) — never hardcode pixel values
- Surface color defines layout hierarchy, not borders — do not add borders between layout regions
- Borders are for interactive elements only (buttons, inputs, clickable cards, floating overlays)
- Icons always come from `lucide-react` — never create inline SVGs or guess icon names
- Navigation hierarchy is strict: `SidebarNavigation` → `SecondaryNav` → `Tabs`. Never skip levels.
- Each logical section gets its own `surface-bg` card — never combine unrelated sections
- Complexity is revealed progressively — hide occasional controls behind expand, hover, or click

setup.md: Design system dependencies

setup.md starts with an initial set of instructions to tell Make to use your design system package instead of the default components included with Figma Make files. However, you can add additional technical instructions and dependencies. This can be useful if you have other files in your Make kit that Figma Make should use when generating results for you.

Example: setup.md

# Project Setup

## Required CSS imports

Import the styles directly from the package into the main .css file to make them available globally

```tsx
import '@brettmcm/astraui/styles.css'
```

Do NOT add `@source` rules for this package in the consumer's Tailwind config. The package ships pre-compiled CSS with all required utility classes.

## Theme provider

Wrap your app root with `ThemeProvider`. This is required for dark mode support and theme persistence.

```tsx
import { ThemeProvider } from '@brettmcm/astraui'

function App() {
  return (
    <ThemeProvider>
      {/* app content */}
    </ThemeProvider>
  )
}
```

`ThemeProvider` reads `localStorage('astra-theme')` on mount and falls back to `prefers-color-scheme`. It manages the `.dark` class on `<html>` automatically.

### Theme hook

Use `useTheme` in any child component to read or toggle the theme:

```tsx
import { useTheme } from '@brettmcm/astraui'

function ThemeToggle() {
  const { theme, toggleTheme, setTheme } = useTheme()
  return <Button onClick={toggleTheme}>{theme}</Button>
}
```

`ThemeProvider` must be an ancestor of any component calling `useTheme()`.

## Build configuration

Astra UI is built with Vite and the `@tailwindcss/vite` plugin. The standard `vite.config.ts` for the library:

```tsx
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})
```

### Library build

Run `npm run build:lib` to produce the distributable package. This outputs:
- ESM (`.mjs`)
- CJS (`.cjs`)
- Pre-compiled CSS

Consumers do NOT need Tailwind configured to use this package — CSS ships pre-compiled.

## Rules

- Do not add `@source` rules for `@brettmcm/astraui` in consumer Tailwind configs
- `ThemeProvider` is required at the app root for dark mode to work
- CSS import order does not matter — there is only one stylesheet
- All styling uses design system tokens mapped via `@theme inline` — use Tailwind classes that reference Astra tokens (e.g. `bg-brand-tertiary`, `gap-xl`), not arbitrary values

Granular overview.md files: overview guidelines

Granular or subfolder overview files are where you can introduce Figma Make to specific aspects of your design system. Common overview files include:

• overview-components.md to explain which components are available and any common usage patterns that apply to all components
• overview-icons.md to explain the icon system available in your design system

Every design system is different. To help Figma Make be as successful as possible with your design system, use these files to educate Figma Make the same way you'd teach an engineer who's new to your design system.

Since many short guidelines files are better than only a few lengthy ones, your granular overview files are important for showing Figma Make where to find the guidelines it needs for its tasks.

Example: overview-components.md

# Component Catalog

Always prefer components from `@brettmcm/astraui` over plain HTML elements. Do NOT write code using a component until you have read its guidelines file.

```tsx
import { Button, Avatar, InputField } from '@brettmcm/astraui'
```

## Buttons & actions

| Component | Alt names | Purpose | Guidelines |
|---|---|---|---|
| Button | CTA, action button | Primary, neutral, subtle actions | button.md |
| IconButton | Icon action, circle button | Icon-only circular action button | button.md |
| ButtonGroup | Button bar, action group | Grouped related actions with alignment | button.md |
| FavoriteButton | Like button, star button | Toggle favorite/star state | button.md |

## Inputs & forms

| Component | Alt names | Purpose | Guidelines |
|---|---|---|---|
| InputField | Text input, text field | Single-line text entry with label/description | input.md |
| TextareaField | Multi-line input, text area | Multi-line text entry with label/description | input.md |
| SelectField | Dropdown, select, picker | Dropdown selection from predefined options | input.md |
| SearchComponent | Search bar, search input | Search with animated placeholder | input.md |
| Checkbox | Check, boolean input | Boolean selection with label/description | input.md |
| RadioGroup | Radio buttons, single select | Mutually exclusive choices | input.md |
| SwitchField | Toggle, switch | On/off toggle setting | input.md |
| PromptInput | Chat input, message input | AI prompt text entry with send/attach | ai-agent.md |

## Navigation

| Component | Alt names | Purpose | Guidelines |
|---|---|---|---|
| SidebarNavigation | Sidebar, nav rail, app shell | Persistent 60px icon rail — every page | navigation.md |
| SidebarButton | Nav icon, sidebar icon | Icon button for SidebarNavigation | navigation.md |
| SecondaryNav | Sub-nav, section nav, side panel | Secondary navigation for sub-sections | navigation.md |
| SecondaryNavItem | Sub-nav item, section link | Item within SecondaryNav | navigation.md |
| Tabs | Tab bar, tab switcher | Tertiary content switching within a section | tabs.md |
| SegmentedControl | Switcher, toggle group | Inline icon switcher | tabs.md |

## Media & content

| Component | Alt names | Purpose | Guidelines |
|---|---|---|---|
| Avatar | Profile image, user photo | User/entity profile image or initials | media.md |
| AvatarGroup | Avatar stack, user group | Grouped avatar display with overflow | media.md |
| ItemCard | Video card, content card | Content card with thumbnail and metadata | media.md |
| DurationBadge | Timecode, duration label | Compact timecode label for video thumbnails | media.md |
| VideoControl | Video player, playback controls | Video playback controls with seek bar | media.md |

## Feedback & status

| Component | Alt names | Purpose | Guidelines |
|---|---|---|---|
| Toast | Notification, snackbar | Brief notification with progress | feedback.md |
| Badge | Label, tag, status pill | Status labels and counters | feedback.md |
| Tooltip | Hint, popover, info tip | Contextual hint on hover/focus | feedback.md |
| Modal | Dialog, popup, overlay | Focused task dialog with backdrop | modal.md |

## AI Agent

| Component | Alt names | Purpose | Guidelines |
|---|---|---|---|
| AIVideoCreation | Video creator, new video prompt | Entry point for AI video generation with suggestion chips | ai-agent.md |
| ChatBubbles | Message, chat message | AI or user chat message bubble | ai-agent.md |
| PromptInput | Chat input, message box | Text input with send/attach for AI prompts | ai-agent.md |
| PromptPane | Chat panel, chat sidebar | Full chat container with messages + input | ai-agent.md |

## Toolbar

| Component | Alt names | Purpose | Guidelines |
|---|---|---|---|
| Toolbar | Tool palette, action bar | Floating toolbar container | toolbar.md |
| ToolbarItem | Tool button, toolbar icon | Icon button within a Toolbar | toolbar.md |

## Layout & utility

| Component | Alt names | Purpose | Guidelines |
|---|---|---|---|
| AstraLogo | Logo, brand mark | Brand mark SVG | navigation.md |
| ThemeProvider | Theme wrapper, dark mode | App root provider for theme management | ../foundations/modes.md |

## Button variant decision tree

```
┌─ "What button variant should I use?"
│
├─ Main call-to-action (one per section)?
│  └─ variant="primary"
│
├─ Supporting action alongside a primary?
│  └─ variant="neutral" ⭐ Default for secondary actions
│
└─ Subtle or low-emphasis action?
   └─ variant="subtle"
```

Rules:
- Only one `primary` button per visible section
- Do not use variant names that don't exist (`"secondary"`, `"ghost"`, `"destructive"`)
- Valid variants are: `"primary"`, `"neutral"`, `"subtle"` — nothing else

## Input component selection

```
┌─ "How should the user provide input?"
│
├─ Choose from mutually exclusive options?
│  └─ RadioGroup
│
├─ Choose from predefined options (dropdown)?
│  └─ SelectField
│
├─ Boolean on/off (setting with label)?
│  └─ SwitchField
│
├─ Boolean on/off (form field)?
│  └─ Checkbox
│
├─ Freeform short text?
│  └─ InputField
│
├─ Freeform long text?
│  └─ TextareaField
│
└─ Search with animated placeholder?
   └─ SearchComponent
```

## Feedback component selection

```
┌─ "How should I show information to the user?"
│
├─ Brief notification with progress?
│  └─ Toast — "Uploading...", "Changes saved"
│
├─ Status label or counter?
│  └─ Badge — "New", "Active", "3 items"
│
├─ Contextual hint on hover?
│  └─ Tooltip — icon button labels, abbreviation explanations
│
└─ Requires user decision or focused task?
   └─ Modal — confirmations, export settings, forms
```

## Navigation hierarchy

```
┌─ "What navigation component should I use?"
│
├─ App-level navigation (always present)?
│  └─ SidebarNavigation + SidebarButton (PRIMARY)
│
├─ Page sub-sections (settings, detail views)?
│  └─ SecondaryNav + SecondaryNavItem (SECONDARY)
│
└─ Content switching within a section?
   └─ Tabs (TERTIARY)
```

IMPORTANT: Never skip navigation levels. Every desktop page includes SidebarNavigation. Use SecondaryNav for sub-sections, not Tabs.

## Common props

Most components accept:
- `className`: String for additional CSS classes
- `disabled`: Boolean to disable the component

Form components additionally accept:
- `label`: Field label text
- `description`: Helper text below the label
- `onChange`: Simplified callback — `(value) => void`, not native event

tokens.md: design token guidelines

To create polished outputs, Figma Make needs to know how to use the tokens that specify your colors, typography, spacing, radii, etc. Like you see in the example file structure, you can actually have multiple files for your tokens. Don’t feel required to stick to just the one tokens.md file initially provided.

We commonly see tokens for colors, typography, and spacing, but you can add guidelines for any token type used by your design system.

In the file for each type of tokens, you should cover:

1. An overall design philosophy of how these tokens are used.
2. Descriptions of overarching groups of tokens, including their naming and usage patterns.
3. Lists of specific tokens along with examples and descriptions of their proper usage.
4. Higher level examples of how different tokens are used together.

Example: typography.md

# Typography Tokens

## Font families

Astra uses a single font family for all UI text:

| Family | Token | Tailwind | Usage |
|---|---|---|---|
| Instrument Sans | `font-sans` | `font-sans` | **All UI text** — body, labels, inputs |
| Instrument Sans | `font-display` | `font-display` | Titles (same family, used semantically) |

Both `font-sans` and `font-display` resolve to `'Instrument Sans', system-ui, sans-serif`. Do not use other font families directly.

## Type scale

Astra uses composite typography classes that bundle size, weight, line height, and extras together. Always use these classes — do not set font-size independently.

| Class | Size | Weight | Line Height | Usage |
|---|---|---|---|---|
| `text-title` | 24px | 600 (SemiBold) | 1.4 | Page titles, major headings |
| `text-heading` | 20px | 500 (Medium) | 1.4 | Section headings |
| `text-caption` | 20px | 600 (SemiBold) | 1.4 | Uppercase captions |
| `text-label` | 16px | 500 (Medium) | 1.4 | Form labels, card section headings, button text |
| `text-label-sm` | 14px | 500 (Medium) | 1.4 | Descriptions, helper text, secondary labels |
| `text-input` | 16px | 400 (Regular) | 1.4 | Input field values |
| `text-input-sm` | 14px | 500 (Medium) | 1.4 | Small input values, DurationBadge text |
| `text-video-title` | 12px | 400 (Regular) | normal | Metadata, timestamps, smallest text |

The dominant text sizes are 16px (`text-label`) and 14px (`text-label-sm`). Do not use arbitrary font sizes — every text element should map to a class from this scale.

## Font weights

| Tailwind | Weight | Usage |
|---|---|---|
| `font-book` | 450 | Occasional — between regular and medium |
| `font-medium` | 500 | **Default for labels and UI text** |
| `font-semibold` | 600 | Titles, section headings, strong emphasis |

Most UI text uses `font-medium` (500) via the composite type classes. Do not use weights outside this set (no 300, 700, 800, or 900).

## Decision tree

```
┌─ "What typography class should I use?"
│
├─ PAGE TITLE (top of page, one per view)?
│  └─ text-title (24px semibold)
│
├─ SECTION HEADING (within page content)?
│  └─ text-heading (20px medium)
│
├─ UPPERCASE CAPTION or label?
│  └─ text-caption (20px semibold, uppercase)
│
├─ CARD SECTION HEADING or form label?
│  └─ text-label (16px medium)
│
├─ DESCRIPTION, helper text, or secondary info?
│  └─ text-label-sm (14px medium)
│
├─ INPUT FIELD VALUE?
│  └─ text-input (16px regular)
│
├─ SMALL INPUT or compact field?
│  └─ text-input-sm (14px medium)
│
└─ METADATA, timestamp, or fine print?
   └─ text-video-title (12px regular)
```

## Line height

All composite type classes include a paired line height of `1.4` (except `text-video-title` which uses `normal`). Do not override line height independently.

```tsx
{/* CORRECT — use the composite class */}
<h1 className="text-title text-text-primary">Page Title</h1>

{/* WRONG — arbitrary size and line height */}
<h1 className="text-2xl leading-8 font-semibold">Page Title</h1>
```

## Common patterns

### Page header
```tsx
<h1 className="text-title text-text-primary">Profile</h1>
<p className="text-label-sm text-text-secondary mt-xs">Manage your account settings</p>
```

### Card section heading
```tsx
<h2 className="text-label text-text-primary font-semibold mb-lg">Personal Information</h2>
```

### Metadata row
```tsx
<span className="text-video-title text-text-primary">Edited 2m ago</span>
```

## Rules

- Always use composite type classes (`text-title`, `text-label`, etc.) — never set `font-size` directly
- Do not use Tailwind's default size classes (`text-sm`, `text-base`, `text-lg`) — use Astra's type scale
- Text color is separate — pair type classes with `text-text-primary`, `text-text-secondary`, or `text-text-tertiary`
- Reduce importance through scale (smaller type class), not opacity — use `text-video-title` at `text-text-primary` rather than `text-label` at `text-text-tertiary`
```

#### Example: `color.md`

```markdown
# Color Tokens

## Color palette overview

Astra uses a primarily neutral palette with a branded lavender canvas. Brand color (`brand-primary`) is used sparingly — only for primary actions, active states, and small accents.

| Role | Value (light) | Token | Frequency | Usage |
|---|---|---|---|---|
| Lavender canvas | `#eaeaff` | `--brand-tertiary` | **Dominant** | Page background canvas |
| White surface | `#ffffff` | `--surface-bg` | **Dominant** | Cards, panels, sidebar, elevated content |
| Black text | `rgba(0,0,0,0.85)` | `--text-primary` | **Dominant** | Primary text |
| Brand purple | `#5250f3` | `--brand-primary` | Sparse | Primary buttons, active tabs, progress bars |
| Dark surface | `#22222c` | `--surface-dark` | Internal | Tooltips, component internals |

The UI is ~90% neutral surfaces (`brand-tertiary` canvas + `surface-bg` cards). Brand color appears only in primary actions, active indicators, and small highlights.

## Naming pattern

Astra tokens follow: `--{category}-{role}`

- **category**: `brand`, `surface`, `text`, `border`, `bg`
- **role**: describes the semantic purpose

| Category | Tokens | Used for |
|---|---|---|
| `brand-*` | `primary`, `hover`, `dark`, `secondary`, `tertiary`, `muted` | Brand identity, actions, canvas |
| `surface-*` | `bg`, `secondary-bg`, `hover`, `dark`, `dark-hover`, `darkest` | Content surfaces, tooltips, component internals |
| `text-*` | `primary`, `secondary`, `tertiary` | Text hierarchy |
| `border-*` | `primary`, `secondary`, `selected` | Interactive element borders |
| `bg-*` | `faint`, `subtle`, `hover` | Background tints within surfaces |
| `on-*` | `brand`, `reverse` | Text on solid color backgrounds |
| Status | `success`, `warning`, `danger` | Semantic status indicators |

## Tailwind class mapping

Tokens are mapped to Tailwind via `@theme inline`. Use these classes — never hardcode hex values.

```
bg-brand-primary, text-brand-primary, border-brand-primary
bg-brand-hover, bg-brand-dark, bg-brand-secondary, bg-brand-tertiary, bg-brand-muted
bg-surface-bg, bg-surface-secondary-bg, bg-surface-hover, bg-surface-dark
text-text-primary, text-text-secondary, text-text-tertiary
border-border-primary, border-border-secondary, border-border-selected
bg-bg-faint, bg-bg-subtle, bg-bg-hover
text-on-brand, text-on-reverse
bg-success, bg-warning, bg-danger
bg-input-bg, bg-modal-scrim
```

## Decision trees

### Background color

```
┌─ "What background color should I use?"
│
├─ Page canvas (main content area)?
│  └─ bg-brand-tertiary
│
├─ Elevated content (card, panel, form container)?
│  └─ bg-surface-bg
│
├─ Sidebar navigation?
│  └─ bg-surface-bg (with border-r border-border-primary)
│
├─ Secondary navigation panel?
│  └─ bg-surface-secondary-bg
│
├─ Recessed area within a card?
│  └─ bg-bg-faint
│
├─ Input field background?
│  └─ bg-input-bg
│
├─ Subtle grouping within a card?
│  └─ bg-bg-subtle
│
├─ Hover state on an interactive region?
│  └─ bg-surface-hover or bg-bg-hover
│
├─ Primary action button?
│  └─ bg-brand-primary + text-on-brand
│
├─ AI chat bubble?
│  └─ bg-brand-secondary (built into ChatBubbles component)
│
├─ Modal backdrop?
│  └─ bg-modal-scrim
│
└─ Status indicator?
   └─ bg-success, bg-warning, or bg-danger
```

### Text color

```
┌─ "What text color should I use?"
│
├─ PRIMARY content users must read?
│  └─ text-text-primary
│
├─ SUPPORTING information (descriptions, helper text, timestamps)?
│  └─ text-text-secondary
│
├─ DECORATIVE or very low priority (placeholders, disabled labels)?
│  └─ text-text-tertiary
│
├─ Interactive text (active tab label, link)?
│  └─ text-brand-primary
│
├─ Text on brand-primary background?
│  └─ text-on-brand (always white)
│
├─ Status text?
│  └─ text-danger, text-success, text-warning
│
└─ Element that must stay dark in both modes?
   └─ text-on-reverse
```

### Border color

```
┌─ "What border color should I use?"
│
├─ Default interactive element (input, select, clickable card)?
│  └─ border-border-primary
│
├─ Subtle separator (secondary divider, card edge)?
│  └─ border-border-secondary
│
├─ Focused or selected element?
│  └─ border-border-selected
│
└─ Layout region boundary?
   └─ No border — use surface color contrast instead
      Exception: SidebarNavigation uses border-r border-border-primary
```

### Icon color

```
Icons inherit text color via currentColor. Follow the text hierarchy:
├─ Primary → text-text-primary (default via currentColor)
├─ Secondary → text-text-secondary
├─ On brand background → text-on-brand
├─ Active/selected → text-brand-primary
└─ Status → text-danger, text-success, text-warning
```

## Token usage by element type

### Buttons
- Primary: `bg-brand-primary` background, `text-on-brand` text
- Neutral: `bg-surface-bg` background, `text-text-primary` text, `border-border-primary` border
- Subtle: transparent background, `text-text-primary` text

### Text
- Body text: `text-text-primary`
- Descriptions, metadata: `text-text-secondary`
- Placeholders: `text-text-tertiary`
- Active tab, link: `text-brand-primary`
- Error message: `text-danger`

### Surfaces
- Page canvas: `bg-brand-tertiary`
- Elevated cards/panels: `bg-surface-bg`
- Sidebar: `bg-surface-bg` with `border-r border-border-primary`
- Recessed areas: `bg-bg-faint` or `bg-bg-subtle`
- Tooltips: `bg-surface-dark` (component internal)

### Icons
- Default: inherits `currentColor` from parent text color
- Active sidebar item: 85% opacity via component
- Status: `text-danger`, `text-success`

## Common mistake: "on-" roles

Use `on-brand` for text on solid brand backgrounds:

```tsx
{/* CORRECT — white text on brand background */}
<div className="bg-brand-primary text-on-brand">Save</div>

{/* WRONG — primary text disappears on brand background */}
<div className="bg-brand-primary text-text-primary">Save</div>
```

`on-reverse` (`#1e1e1e`) is for elements that must stay dark in both light and dark modes — e.g., the dot separator in `ItemCard` metadata.

## Common mistake: brand color overuse

IMPORTANT: `brand-primary` and `brand-secondary` are for small accents only. Never use them as backgrounds for cards, panels, sections, or large areas.

```tsx
{/* CORRECT — brand on a button */}
<Button variant="primary">Save</Button>

{/* WRONG — brand as a section background */}
<div className="bg-brand-primary p-xl">
  <h2>Welcome</h2>
</div>
```

components.md: component guidelines

To help Make full use of components from your design system, especially more complex components that require a particular style of usage or complex configuration, you can provided detailed documentation for your each of your components. Similar to above, don’t feel constrained by the initial components.md file. You can provide additional guidelines files for specific components in your design system.

In the file for each component, you should cover:

1. When to use the component, including the other components it's commonly used with or within
2. The semantic purpose of the component
3. Examples of correct & incorrect usage patterns
4. The API of the component, including its properties

Example: button.md

# Button

## When to use

Use Button for all interactive actions — form submissions, navigation triggers, and commands. Always use the `Button` component from `@brettmcm/astraui`, never a raw `<button>` element.

## Variants

| Variant | Frequency | Use for |
|---|---|---|
| `primary` | ~30% | Main CTA — one per visible section |
| `neutral` | ~50% | **Default — most actions**, supporting actions alongside primary |
| `subtle` | ~20% | Low-emphasis actions, text-like buttons |

IMPORTANT: Valid variants are `"primary"`, `"neutral"`, `"subtle"` — nothing else. Do NOT use `"secondary"`, `"ghost"`, `"destructive"`, or `"link"`.

## Variant decision tree

```
┌─ "What button variant should I use?"
│
├─ Main call-to-action (one per section)?
│  └─ variant="primary"
│
├─ Supporting action alongside a primary?
│  └─ variant="neutral" ⭐ Default
│
└─ Subtle or low-emphasis action?
   └─ variant="subtle"
```

## Sizing

| Size | Height | Usage |
|---|---|---|
| `medium` | Default | **Most cases** — standard actions |
| `small` | Compact | Dense UI, inline actions, secondary controls |

## Props

| Prop | Type | Default |
|---|---|---|
| `variant` | `'primary' \| 'neutral' \| 'subtle'` | `'primary'` |
| `size` | `'medium' \| 'small'` | `'medium'` |
| `iconStart` | `ReactNode` | — |
| `iconEnd` | `ReactNode` | — |
| `disabled` | `boolean` | `false` |
| `className` | `string` | — |

Also accepts all native `<button>` HTML attributes.

## Usage notes

- Icons use `iconStart` and `iconEnd` props — NOT `leftIcon`, `rightIcon`, or `icon`
- Use `size={16}` on icons passed to `iconStart`/`iconEnd`
- Buttons are pill-shaped (`rounded-corner-full`)

## Examples

```tsx
import { Button } from '@brettmcm/astraui'
import { Plus, ArrowRight, Trash2 } from 'lucide-react'

{/* Primary CTA */}
<Button variant="primary">Save Changes</Button>

{/* Neutral supporting action */}
<Button variant="neutral">Cancel</Button>

{/* With icons */}
<Button variant="primary" iconStart={<Plus size={16} />}>Add Item</Button>
<Button variant="subtle" iconEnd={<ArrowRight size={16} />}>Next</Button>

{/* Small size */}
<Button variant="neutral" size="small">Change Photo</Button>
```

---

# IconButton

## When to use

Use IconButton for icon-only actions where a text label isn't needed — toolbars, compact controls, close buttons. Shares the same variant and size system as Button but renders as a circle with no label.

## Props

| Prop | Type | Default |
|---|---|---|
| `icon` | `ReactNode` | required |
| `variant` | `'primary' \| 'neutral' \| 'subtle'` | `'primary'` |
| `size` | `'medium' \| 'small'` | `'medium'` |
| `disabled` | `boolean` | `false` |
| `className` | `string` | — |

Also accepts all native `<button>` HTML attributes.

## Sizing

| Size | Dimensions |
|---|---|
| `medium` | 40×40px |
| `small` | 32×32px |

## Usage notes

- Always circular (`rounded-full`) — not pill-shaped like Button
- Use `subtle` variant for most icon-only actions to keep the UI minimal
- Pair with `Tooltip` so users can discover the action on hover
- Prefer `Button` with a label when there's room — icon-only buttons are harder to understand

## Example

```tsx
import { IconButton } from '@brettmcm/astraui'
import { Plus, X, Settings } from 'lucide-react'

{/* Primary action */}
<IconButton icon={<Plus size={16} />} variant="primary" />

{/* Subtle close button */}
<IconButton icon={<X size={16} />} variant="subtle" size="small" />

{/* Neutral with outline */}
<IconButton icon={<Settings size={16} />} variant="neutral" />
```

---

# ButtonGroup

## When to use

Use ButtonGroup to layout related actions together with consistent alignment.

## Props

| Prop | Type | Default |
|---|---|---|
| `children` | `ReactNode` | required |
| `align` | `'justify' \| 'start' \| 'end' \| 'center' \| 'stack'` | `'justify'` |
| `className` | `string` | — |

## Alignment options

| Align | Behavior |
|---|---|
| `justify` | Full-width, space-between with equal flex |
| `start` | Horizontal, aligned left |
| `end` | Horizontal, aligned right |
| `center` | Horizontal, centered |
| `stack` | Vertical with full-width buttons |

## Example

```tsx
import { Button, ButtonGroup } from '@brettmcm/astraui'

{/* Form footer — cancel + save */}
<ButtonGroup align="end">
  <Button variant="neutral">Cancel</Button>
  <Button variant="primary">Save</Button>
</ButtonGroup>

{/* Full-width justified */}
<ButtonGroup align="justify">
  <Button variant="neutral">Back</Button>
  <Button variant="primary">Continue</Button>
</ButtonGroup>
```

---

# FavoriteButton

## When to use

Use FavoriteButton for toggle favorite/star actions on content items. Typically overlays video thumbnails or appears alongside metadata.

## Props

| Prop | Type | Default |
|---|---|---|
| `defaultFavorited` | `boolean` | `false` |
| `onChange` | `(favorited: boolean) => void` | — |
| `className` | `string` | — |

Also accepts all native `<button>` HTML attributes.

## Usage notes

- 24px circular toggle button
- Uses `surface-bg` background that adapts to dark mode
- Stroked `Star` icon when inactive, filled `brand-primary` star when favorited
- Designed to overlay video thumbnails — works on both light and dark backgrounds

## Example

```tsx
import { FavoriteButton } from '@brettmcm/astraui'

<FavoriteButton defaultFavorited={false} onChange={(fav) => console.log(fav)} />
```

---

## Rules

- Only one `primary` button per visible section
- All buttons in a group must use the same size variant — do not mix `medium` and `small`
- Do not use variant names that don't exist — only `"primary"`, `"neutral"`, `"subtle"`
- Primary action button goes on the right in button groups (Cancel left, Save right)
- Use `iconStart`/`iconEnd` for icons — not children or other prop names

What’s next?

For more inspiration, you can check out the best practices for library styles in Make kits. While design packages require more granular guidelines than library styles, there are still some useful tidbits in the best practices. See Bring style context from a Figma Design library to Make kits in the Help Center.

When you’re done crafting your guidelines, you’re ready to finish the last steps of assembling your Make kit. Follow the steps in Get started with Make kits to wrap up the work.