# FT Design System - AI Context
# Machine-readable rules for LLMs and AI coding assistants
# Version: 5.0.5

## IDENTITY
name: ft-design-system
type: react-component-library
package: ft-design-system
version: 5.0.5

## WORKFLOW CONTRACT (MANDATORY)
- Before writing or modifying any UI code, read the relevant files under `specs/`.
- Before commit or PR, run `npm run check:tokens`.
- Before commit or PR for UI/component changes, run `npm run check:consistency`.
- Before commit or PR for component size or variant changes, run `npm run check:size-contract`.
- Before commit or PR touching explorer configs, run `npm run check:explorer-inspector`.
- New component layouts or explorer rows must include/update `parameters.explorer.inspector` metadata.
- Before merging dependency updates, run `npm run check:drift`.
- Before publishing, run `npm run publish:prepare` (includes `npm run sync:docs`).
- Do not add hardcoded visual values unless explicitly approved and documented.
- For PR reviews, follow the checklist at `specs/review-checklist.md`.

## IMPORTS (CRITICAL - USE EXACTLY AS SHOWN)
css: import 'ft-design-system/styles';
components: import { Button, Input, Table } from 'ft-design-system';
components_unprotected: import { Button, Input, Table } from 'ft-design-system/core';
provider: import { FTProvider } from 'ft-design-system';
tailwind_preset: require('ft-design-system/tailwind-preset')

## SETUP (CHOOSE ONE)
setup_auto: <FTProvider theme="system"><App /></FTProvider>
setup_manual: import 'ft-design-system/styles'; + import from 'ft-design-system'
setup_cli: npx ftds setup

## NOTE
All components are AI-protected by default. Use /core only if you need unprotected versions.

## FORBIDDEN PATTERNS (AI MUST NEVER GENERATE)
- Arbitrary hex colors: bg-[ #xxx ], text-[ #xxx ], border-[ #xxx ]
- Arbitrary CSS vars: bg-[ var(--x) ], text-[ var(--x) ]
- Height overrides on components: h-[ x ]
- Width overrides on components: w-[ x ] (except w-full allowed)
- Border radius overrides: rounded-[ x ]
- Padding overrides: p-[ x ], px-[ x ], py-[ x ]
- Hardcoded pixels: fontSize: '16px'
- Hardcoded fonts: fontFamily: 'Inter'
- Underscore in CSS var: var(--border_primary)
- Slash in CSS var: var(--font/family/title)

## ALLOWED PATTERNS
- bg-primary-700, bg-primary-800, bg-secondary, bg-tertiary
- text-primary, text-secondary, text-tertiary
- border-border-primary, border-border-secondary
- size="sm" | size="md" | size="lg" props
- variant="primary" | variant="secondary" | variant="destructive"
- Semantic color classes from tailwind-preset

## COMPONENT API RULES
Button:
  variants: primary | secondary | destructive | text | link | ghost | dashed
  sizes: sm (36px) | md (40px) | lg (48px)
  props: variant, size, icon, iconPosition, loading, disabled, asChild

Input:
  sizes: sm | md | lg
  props: label, placeholder, error, helperText, size, disabled

Table:
  columns: [{key: string, title: string}]  # NOT 'header'
  data: [{id: required, ...}]  # rows MUST have 'id'

Badge:
  variants: primary | secondary | danger | success | warning | neutral
  # NOT 'error' - use 'danger'

Select/Dropdown:
  sizes: md (40px) | lg (52px) | xl (64px)
  use: options prop or composable <SelectItem> children

Modal/Drawer:
  use: open, onOpenChange props
  structure: ModalTrigger, ModalContent, ModalHeader, ModalBody, ModalFooter

## COLOR TOKENS (Reference Only - Use Classes)
primary-700: #434F64  → use bg-primary-700
primary-800: #2c3547  → use bg-primary-800
tertiary: #838C9D     → use text-tertiary
critical: #ff3532    → use text-critical
positive: #00c637    → use text-positive
warning: #ff6c19     → use text-warning
neutral: #1890ff     → use text-neutral

## TYPOGRAPHY (Use rem classes)
text-xs-rem=12px, text-xxs-rem=10px, text-sm-rem=14px
text-md-rem=16px, text-lg-rem=20px, text-xl-rem=24px
text-xxl-rem=28px, text-3xl-rem=36px, text-4xl-rem=48px
text-3_5xl-rem=40px, text-5xl-rem=72px

## SPACING (8-point grid, use --spacing-x* canonical names)
--spacing-x0: 0px, --spacing-x1: 4px, --spacing-x2: 8px, --spacing-x3: 12px
--spacing-x4: 16px, --spacing-x5: 20px, --spacing-x6: 24px, --spacing-x7: 28px
--spacing-x8: 32px, --spacing-x9: 36px, --spacing-x10: 40px, --spacing-x11: 44px
--spacing-x12: 48px, --spacing-x13: 52px, --spacing-x14: 56px, --spacing-x15: 60px
--spacing-x16: 64px, --spacing-x20: 80px, --spacing-x24: 96px, --spacing-x38: 152px
Half-steps: --spacing-x1-5: 6px, --spacing-x2-5: 10px, --spacing-x3-5: 14px

## BORDER RADIUS
--radius-none=0px, --radius-sm=4px, --radius-md=8px, --radius-lg=12px, --radius-xl=16px, --radius-2xl=20px, --radius-3xl=24px, --radius-4xl=28px, --radius-2xs=2px, --radius-smd=6px, --radius-full=9999px

## RESOURCES
registry: ft-design-system/registry
schema: ft-design-system/schema
examples: ft-design-system/examples
docs: https://ft-design-system.dev

## MACHINE ENTRYPOINTS (text/plain, server-rendered)
docs_intro: /machine/docs
components: /machine/docs/components/<component>
ai_prompts: /machine/docs/ai-prompts
designers: /machine/docs/for-designers
developers: /machine/docs/for-developers
storybook: /machine/docs/storybook
npm_package: /machine/docs/npm-package
global_css: /machine/docs/global-css
accessibility: /machine/docs/accessibility
migrations: /machine/docs/migrations
icons: /machine/icons
colors: /machine/colors

## MACHINE ENTRYPOINTS (client-toggle, legacy)
mode: append ?view=machine on ft-docs routes for interactive toggle
docs_intro: /docs?view=machine
components: /docs/components/<component>?view=machine
ai_prompts: /docs/ai-prompts?view=machine
designers: /docs/for-designers?view=machine
developers: /docs/for-developers?view=machine
storybook: /docs/storybook?view=machine
npm_package: /docs/npm-package?view=machine
global_css: /docs/global-css?view=machine
accessibility: /docs/accessibility?view=machine
migrations: /docs/migrations?view=machine
icons: /icons?view=machine
colors: /colors?view=machine
charts: /charts/<chart>?view=machine

## COMPONENT COUNT
total: 134
atoms: 28
molecules: 63
organisms: 25
charts: 16

## QUICK EXAMPLES
button_primary: <Button variant="primary" size="md">Save</Button>
button_destructive: <Button variant="destructive">Delete</Button>
input_basic: <Input label="Email" size="md" placeholder="Enter email" />
table_basic: <Table columns={[{key:'name',title:'Name'}]} data={[{id:1,name:'John'}]} />
badge_danger: <Badge variant="danger">Error</Badge>
modal_basic: <Modal open={open} onOpenChange={setOpen}><ModalContent>...</ModalContent></Modal>