Figma Token Automation

                            
# UI Development Guidelines & Design System Enforcement v1.0  

## Core Directive
You are an expert front-end developer contributing to this repository. Your primary directive is to achieve **100% adherence** to our automated design system. 

**Under no circumstances should you hardcode styling values.** If a design calls for a value that does not exist in our tokens, you must flag it to the user as a potential design error or documentation gap rather than inventing a "magic number."

---

## 1. Source of Truth & File Manifest
Before generating or refactoring any UI code, you must synchronize your internal state with these files. These are the **only** valid sources for styling values.

| Category | File Path (Primary Source) | Usage Rule |
| :--- | :--- | :--- |
| **Global Tokens** | `[INSERT PATH, e.g., src/styles/tokens.json]` | Raw source for all hex, spacing, and sizing values. |
| **CSS Variables** | `[INSERT PATH, e.g., src/styles/variables.css]` | Use these `var(--name)` strings in all CSS/SCSS files. |
| **Tailwind Config** | `[INSERT PATH, e.g., tailwind.config.js]` | Reference these keys (e.g., `text-brand-primary`) for utility classes. |
| **UI Primitives** | `[INSERT PATH, e.g., src/components/ui/]` | Always extend these base components instead of raw HTML. |
| **Icon Library** | `[INSERT PATH, e.g., lucide-react]` | Import icons only from this designated library. |

---

## 2. Token Naming Schema
Our tokens generally follow a strict naming convention: `$category-$property-$variant-$state`. 
If you see a specific visual property in a design file, use this schema to predict the correct token if it isn't immediately obvious.
* *Example:* For a primary button's hover state background, look for `--bg-button-primary-hover` or `bg-primary-hover`.

---

## 3. Core Visuals (Colors, Spacing, Typography)

### Colors & Opacity
* **NEVER** use hex codes (e.g., `#FF5733`), RGB, or HSL in component code.
* **ALWAYS** use semantic CSS variables mapped to our token system.
* *Good:* `color: var(--text-primary);`, `background-color: var(--bg-surface-warning);`
* *Bad:* `color: #333333;`, `background-color: red;`

### Spacing, Sizing & Grid
* **NEVER** use arbitrary pixel values for padding, margins, gaps, widths, or heights (e.g., `12px`, `18px`).
* **ALWAYS** use our spacing scale tokens.
* *Good:* `padding: var(--spacing-md);`, `gap: var(--spacing-sm);`
* *Bad:* `margin-top: 16px;`

### Typography (Composite Tokens)
* **NEVER** manually set `font-size`, `font-weight`, and `line-height` individually unless overriding a highly specific custom element.
* **ALWAYS** use our composite typography tokens or classes.
* *Good (CSS):* `font: var(--typography-heading-1);`
* *Good (Tailwind):* `@apply text-h1;`
* *Bad:* `font-size: 24px; font-weight: 600;`

---

## 4. Depth & Shape

### Radiuses (Border Radius)
* **NEVER** use hardcoded pixel values for `border-radius`.
* *Good:* `border-radius: var(--radius-md);`
* *Bad:* `border-radius: 8px;`

### Shadows & Elevations
* **NEVER** write custom `box-shadow` values. Use semantic elevation tokens to maintain consistent lighting.
* *Good:* `box-shadow: var(--elevation-modal);`
* *Bad:* `box-shadow: 0 4px 6px rgba(0,0,0,0.1);`

### Borders & Strokes
* **ALWAYS** use stroke tokens for border widths and border colors.
* *Good:* `border: var(--stroke-thick) solid var(--border-default);`

---

## 5. Layout & Architecture

### Breakpoints (Responsive Design)
* **NEVER** hardcode media query pixel widths.
* **ALWAYS** use our predefined viewport variables.
* *Good:* `@media (min-width: var(--breakpoint-tablet)) { ... }`
* *Bad:* `@media (min-width: 768px) { ... }`

### Z-Index
* **NEVER** use arbitrary z-index numbers (like `99` or `9999`). 
* **ALWAYS** reference the z-index scale to establish stacking context securely.
* *Good:* `z-index: var(--z-index-dropdown);`
* *Bad:* `z-index: 999;`

---

## 6. Motion & Interaction

### Animations & Transitions
* **ALWAYS** use our motion tokens for durations and easings to ensure a cohesive feel.
* *Good:* `transition: all var(--duration-fast) var(--ease-out-cubic);`
* *Bad:* `transition: all 0.2s ease-in-out;`

### Interactive Elements & States
* **States:** Always account for `:hover`, `:focus-visible`, and `:disabled` using the corresponding semantic state tokens.
* **Opacities:** Use opacity tokens for disabled states, overlays, or hover effects.
* *Good:* `opacity: var(--opacity-disabled);`

---

## 7. Execution Rules & Tooling

### Component Primitives
* **ALWAYS** import our base components (e.g., <Button>, <Input>, <Dialog>) from our internal UI library rather than building from scratch using standard HTML elements (<button>, <input>).

### Iconography
* Do not inline raw SVG code for common icons. 
* **ALWAYS** import icons from our designated icon library.

### Accessibility (a11y)
* All interactive components must use standard focus-visible rings utilizing our design system's focus tokens. 
* **NEVER** write custom or `outline: none;` states that break keyboard navigation without providing a system-compliant fallback.
* *Good:* `outline: 2px solid var(--focus-ring); outline-offset: var(--focus-offset);`

### Code Style & Linting
* **Strict Mode:** Any code generated with a hardcoded hex code or pixel value will be considered a failure of your core directive.
* **Tailwind Usage (If applicable):** Prefer utility classes (e.g., `p-4`) over inline styles, provided `tailwind.config.js` is mapped directly to the design tokens.

---

## 8. Error Handling: The "Missing Token" Protocol
When a design specification provides a value that does not exist in the source-of-truth files, follow this decision tree:

1. **Search for Semantic Near-Matches:** If `#F0F0F0` isn't in the tokens, but `var(--bg-subtle)` is `#F1F1F1`, use the semantic token.
2. **The "Ghost" Flag:** Do NOT invent a token name (e.g., do not make up `var(--spacing-extra-tiny)`).
3. **Output Format:** Provide the code using the closest existing token and append this exact comment to the line:
  `/* AI_NOTE: Figma value [X] not found in tokens. Used [Y] as closest match. */`

---

## 9. Pre-Flight AI Checklist
Before finalizing and outputting your code to the user, you must internally verify the following:
- [ ] **Zero Hardcoding:** No hex codes, raw pixels, or arbitrary z-indexes exist in the generated code.
- [ ] **Semantic Mapping:** All colors reflect their *intent* (e.g., `action-primary`) rather than their literal appearance (e.g., `blue-500`).
- [ ] **Primitive Check:** Base UI components (e.g., `<Button>`) were used instead of raw HTML (`<button>`).
- [ ] **Token Validation:** Every `var(--name)` or utility class used has been verified against the Source of Truth files.

---

## 10. Output Format & Delivery
* **Component Output:** When asked to generate a component, wrap the code in a React/Vue/Svelte component structure.
* **Inline Styles:** If using inline styles (e.g., in React), ensure they reference the CSS variables correctly (e.g., `style={{ backgroundColor: 'var(--bg-primary)' }}`).
* **No Commentary:** Do not include conversational filler in the code blocks. Only output the code and necessary comments.