"
},
{
"name": "Tab",
"kind": "subcomponent",
"required": true,
"description": "Repeatable label, optional icon, and indicator.",
"codeMapping": "Tab data item"
},
{
"name": "Tab panel",
"kind": "helper",
"required": true,
"description": "Consumer-owned related content panel.",
"codeMapping": "useTabPanelProps"
}
],
"contentLimits": [
{
"target": "Tabs",
"limit": "Recommended two to five peer views",
"overflowBehavior": "Use page navigation or another information architecture for larger sets.",
"rationale": "All labels should remain visible without horizontal ambiguity."
},
{
"target": "Tab label",
"limit": "One or two words, maximum 20 characters",
"overflowBehavior": "Do not truncate.",
"rationale": "Short labels improve comparison and keyboard predictability."
}
],
"localization": {
"translatable": [
"Tab list label",
"Tab labels"
],
"rtlBehavior": [
"Visual order follows document direction.",
"Left and right arrow expectations must be tested for the supported browser behavior."
],
"stressCases": [
"Test all labels at twice English length.",
"Test panel relationships after translation."
]
},
"responsive": {
"strategy": "Intrinsic single row owned by its container.",
"breakpoints": [
"Parent-selected narrow breakpoint"
],
"behavior": [
"Do not wrap tab rows.",
"Use horizontal scrolling only with an explicit overflow affordance, otherwise choose a different navigation pattern."
]
},
"limitations": {
"figma": [
"Prototype active variants do not validate roving focus or panel relationships."
],
"code": [
"Consumers must pass the same stable id to Tabs and useTabPanelProps."
],
"notApplicable": []
},
"governance": {
"status": "stable",
"ownerRole": "Design systems navigation primitive owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/components/Tabs.tsx",
"changePolicy": [
"Changes to tab order or activation require keyboard and information-architecture review.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
},
{
"id": "dialog",
"name": "Dialog",
"category": "Overlays",
"purpose": "Presents focused content above the current page.",
"useWhen": [
"Short focused tasks or decisions"
],
"avoidWhen": [
"Persistent page content"
],
"api": [
{
"prop": "open",
"type": "boolean",
"defaultValue": "required",
"description": "Whether the dialog is shown."
},
{
"prop": "onClose",
"type": "() => void",
"defaultValue": "required",
"description": "Called on dismissal."
},
{
"prop": "title",
"type": "string",
"defaultValue": "undefined",
"description": "Optional accessible title."
},
{
"prop": "description",
"type": "string",
"defaultValue": "undefined",
"description": "Optional description."
},
{
"prop": "size",
"type": "DialogSize",
"defaultValue": "md",
"description": "sm, md, lg, or xl."
},
{
"prop": "children",
"type": "ReactNode",
"defaultValue": "required",
"description": "Dialog content."
}
],
"states": [
"closed",
"open",
"entering",
"leaving"
],
"accessibility": [
"Headless UI manages focus, Escape, and restoration.",
"Title and description are associated when provided."
],
"composition": [
"Keep the primary action and close affordance inside the dialog."
],
"code": "
",
"slug": "dialog",
"summary": "A ready-made animated modal dialog for a short focused task or decision.",
"sourcePath": "src/components/Dialog.tsx",
"packageExports": [
"Dialog",
"DialogProps",
"DialogSize"
],
"anatomy": [
{
"name": "Backdrop",
"description": "Full-viewport overlay separating the dialog from page content.",
"required": true
},
{
"name": "Dialog panel",
"description": "Centered bounded content surface.",
"required": true
},
{
"name": "Header",
"description": "Optional title, description, and close button.",
"required": false
},
{
"name": "Close action",
"description": "44 × 44px labelled dismiss button.",
"required": false,
"semanticElement": "button"
},
{
"name": "Body",
"description": "Consumer task content.",
"required": true
}
],
"visualSpec": {
"measurements": [
{
"property": "Viewport padding",
"value": "16px"
},
{
"property": "Panel max width",
"value": "384 / 512 / 672 / 896px",
"notes": "sm / md / lg / xl."
},
{
"property": "Radius",
"value": "6px"
},
{
"property": "Header padding",
"value": "20px horizontal mobile / 24px md; 12px vertical"
},
{
"property": "Body padding",
"value": "24px horizontal / 20px vertical"
},
{
"property": "Close target",
"value": "44 × 44px"
},
{
"property": "Close glyph",
"value": "24 × 24px"
},
{
"property": "Close glyph inset",
"value": "16px from top and logical end",
"notes": "The target is positioned independently so it does not make a title-only header taller."
}
],
"rules": [
"Keep the title visible and specific.",
"Use the shared overlay header and close-control pattern.",
"Hover strengthens the icon without drawing a border; keyboard focus retains the standard outline.",
"Use one scroll strategy; Dialog itself does not constrain body height.",
"Keep primary and dismissal actions inside the panel."
],
"responsiveBehavior": [
"Panel width is fluid up to its size max-width and viewport padding.",
"Consider Modal for long or structurally rich content."
]
},
"designTokens": [
{
"token": "--color-overlay",
"purpose": "Backdrop."
},
{
"token": "--color-surface",
"purpose": "Panel."
},
{
"token": "--color-border",
"purpose": "Panel and header divider."
},
{
"token": "--color-text / --color-text2 / --color-text3",
"purpose": "Title, description, and close icon."
},
{
"token": "--color-focus",
"purpose": "Close focus outline."
}
],
"stateDefinitions": [
{
"name": "closed",
"trigger": "open is false.",
"visual": "Backdrop and panel are absent after transition.",
"behavior": "Page remains interactive."
},
{
"name": "open",
"trigger": "open is true.",
"visual": "Backdrop and centered panel are visible.",
"behavior": "Focus is trapped and background interaction is inert."
},
{
"name": "entering",
"trigger": "Opening transition.",
"visual": "Backdrop fades; panel fades and scales from 95% over 200ms.",
"behavior": "Dialog becomes the active focus scope."
},
{
"name": "leaving",
"trigger": "Closing transition.",
"visual": "Backdrop and panel fade; panel scales to 95% over 150ms.",
"behavior": "Focus returns after dismissal."
}
],
"keyboard": [
{
"key": "Escape",
"action": "Requests close through onClose."
},
{
"key": "Tab / Shift+Tab",
"action": "Cycles focus within the open dialog."
},
{
"key": "Enter / Space",
"action": "Activates the focused dialog control."
}
],
"accessibilitySpec": {
"semantics": "Headless UI dialog with optional DialogTitle and Description associations.",
"accessibleName": "title supplies the accessible name when provided; otherwise body content must provide an accessible label.",
"requirements": [
"Prefer always providing a title.",
"Provide at least one obvious dismissal method.",
"Do not put another modal dialog inside Dialog.",
"Restore focus to a meaningful trigger through the managed open state."
]
},
"implementation": {
"importStatement": "import { Dialog } from '@ai-created/ui';",
"clientComponent": true,
"notes": [
"Headless UI manages focus trap, Escape, outside dismissal, inert background, and restoration.",
"Dialog stays in the tree while Transition controls visibility.",
"className applies to the panel."
]
},
"guidance": {
"dos": [
"Use for one short task with a clear completion path.",
"Write titles that describe the task, not generic “Dialog”."
],
"donts": [
"Do not use for persistent workspace content.",
"Do not put large multi-step flows into the panel."
]
},
"testing": {
"unit": [
"Maps sizes and optional header content.",
"Calls onClose from close button and managed dismissal."
],
"interaction": [
"Opening focus, focus trap, Escape, close button, backdrop, and restoration work."
],
"accessibility": [
"Dialog has a name/description and background is inert while open."
],
"visual": [
"Capture all sizes, header combinations, entering/open states, long content, and themes."
]
},
"relatedComponents": [
"modal",
"confirm-dialog",
"button"
],
"controls": {
"open": {
"type": "boolean",
"label": "Open",
"defaultValue": false
},
"size": {
"type": "select",
"label": "Size",
"defaultValue": "md",
"options": [
"sm",
"md",
"lg",
"xl"
]
},
"title": {
"type": "text",
"label": "Title",
"defaultValue": "Rename project"
}
},
"construction": {
"asset": {
"kind": "component",
"figmaName": "Components/Overlays/Dialog",
"localName": "Dialog",
"canvasApplicability": "Publish size variants with open state, title, description, and nested body content."
},
"autoLayout": {
"applicable": true,
"direction": "vertical",
"gap": "0px between framed regions",
"padding": "16px viewport inset; 20px mobile / 24px desktop header inset; 12px header block padding; close target pinned 6px from the top and logical end",
"alignment": "Stretch",
"wrap": "Content wraps",
"notes": []
},
"resizing": {
"applicable": true,
"width": "fill",
"height": "hug",
"minWidth": "280px",
"maxWidth": "sm 384px; md 512px; lg 672px; xl 896px",
"minHeight": "Content controlled",
"maxHeight": "Viewport minus 32px",
"overflow": "auto",
"notes": []
},
"exposedProperties": [
{
"name": "open",
"label": "Open",
"type": "boolean",
"required": true,
"defaultValue": false,
"codeMapping": "open"
},
{
"name": "size",
"label": "Size",
"type": "variant",
"required": false,
"defaultValue": "md",
"options": [
"sm",
"md",
"lg",
"xl"
],
"codeMapping": "size"
},
{
"name": "title",
"label": "Title",
"type": "text",
"required": false,
"defaultValue": null,
"codeMapping": "title"
},
{
"name": "description",
"label": "Description",
"type": "text",
"required": false,
"defaultValue": null,
"codeMapping": "description"
},
{
"name": "content",
"label": "Content",
"type": "slot",
"required": true,
"defaultValue": null,
"codeMapping": "children"
}
],
"nestedAssets": [
{
"name": "Backdrop",
"kind": "primitive",
"required": true,
"description": "Full viewport modal overlay.",
"codeMapping": "Internal fixed overlay"
},
{
"name": "Panel",
"kind": "primitive",
"required": true,
"description": "Focused dialog surface.",
"codeMapping": "Headless UI DialogPanel"
},
{
"name": "Header",
"kind": "subcomponent",
"required": false,
"description": "Title, description, and close action.",
"codeMapping": "Internal header"
},
{
"name": "Body",
"kind": "slot",
"required": true,
"description": "Focused task content.",
"codeMapping": "children"
}
],
"contentLimits": [
{
"target": "Title",
"limit": "One line preferred, maximum two lines",
"overflowBehavior": "Wrap; do not truncate.",
"rationale": "Users need a concise task name."
},
{
"target": "Description",
"limit": "Maximum three lines",
"overflowBehavior": "Move long instructions into the body.",
"rationale": "Header copy should orient, not explain the whole task."
},
{
"target": "Task scope",
"limit": "One focused task or decision",
"overflowBehavior": "Move complex multi-section work to a page.",
"rationale": "Dialogs interrupt the underlying workflow."
}
],
"localization": {
"translatable": [
"Title",
"Description",
"Body",
"Action labels"
],
"rtlBehavior": [
"Close action stays at logical end.",
"Content follows locale direction."
],
"stressCases": [
"Test twice-length titles.",
"Test at 200% zoom with keyboard-only dismissal."
]
},
"responsive": {
"strategy": "Width is capped by size and inset 16px from the viewport.",
"breakpoints": [
"No internal breakpoint"
],
"behavior": [
"Panel shrinks to viewport width.",
"Body must remain reachable when content exceeds viewport height."
]
},
"limitations": {
"figma": [
"Figma overlays cannot validate focus trapping, restoration, Escape, or scroll lock."
],
"code": [
"Always provide an accessible title through title or a correctly associated custom heading."
],
"notApplicable": []
},
"governance": {
"status": "stable",
"ownerRole": "Design systems overlay primitive owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/components/Dialog.tsx",
"changePolicy": [
"Dismissal, focus, or size changes require overlay accessibility review.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
},
{
"id": "modal",
"name": "Modal family",
"category": "Overlays",
"purpose": "Composes a themed modal from overlay, panel, header, body, and footer.",
"useWhen": [
"Reusable application modal layouts"
],
"avoidWhen": [
"Simple inline disclosure"
],
"api": [
{
"prop": "ModalOverlay.onClose",
"type": "() => void",
"defaultValue": "undefined",
"description": "Dismiss callback."
},
{
"prop": "ModalOverlay.closeOnBackdrop",
"type": "boolean",
"defaultValue": "true",
"description": "Whether backdrop clicks dismiss."
},
{
"prop": "ModalPanel.size",
"type": "ModalSize",
"defaultValue": "lg",
"description": "sm, md, lg, or xl."
},
{
"prop": "ModalHeader.heading",
"type": "ReactNode",
"defaultValue": "required",
"description": "Heading content."
},
{
"prop": "ModalHeader.onClose",
"type": "() => void",
"defaultValue": "undefined",
"description": "Optional close action."
},
{
"prop": "ModalBody.scroll",
"type": "boolean",
"defaultValue": "true",
"description": "Allows the body region to scroll."
},
{
"prop": "children",
"type": "ReactNode",
"defaultValue": "required",
"description": "Content for each region."
}
],
"states": [
"closed",
"open",
"nested",
"focus-visible"
],
"accessibility": [
"Headless UI supplies focus trap, Escape, restoration, and scroll lock.",
"Header title and description are associated."
],
"composition": [
"Compose ModalOverlay > ModalPanel > ModalHeader, ModalBody, and ModalFooter."
],
"code": "
......",
"slug": "modal",
"summary": "A composable Headless UI modal shell for richer application layouts with header, body, and footer regions.",
"sourcePath": "src/components/Modal.tsx",
"packageExports": [
"ModalOverlay",
"ModalPanel",
"ModalHeader",
"ModalBody",
"ModalFooter",
"ModalSize"
],
"anatomy": [
{
"name": "Overlay",
"description": "Mounted dialog root, scroll container, backdrop, and focus scope.",
"required": true
},
{
"name": "Panel",
"description": "Bounded flex-column Surface.",
"required": true
},
{
"name": "Header",
"description": "Optional eyebrow, title, description, custom content, and close action.",
"required": true
},
{
"name": "Body",
"description": "Primary content region with optional internal scrolling.",
"required": true
},
{
"name": "Footer",
"description": "Optional bordered action region.",
"required": false
}
],
"visualSpec": {
"measurements": [
{
"property": "Panel max width",
"value": "384 / 512 / 672 / 896px",
"notes": "sm / md / lg / xl; shared with Dialog."
},
{
"property": "Panel max height",
"value": "viewport − 48px mobile / viewport − 64px md+"
},
{
"property": "Overlay padding",
"value": "16px mobile / 24px md+"
},
{
"property": "Top offset mobile",
"value": "64px"
},
{
"property": "Header padding",
"value": "20px horizontal mobile / 24px md; 12px vertical"
},
{
"property": "Body/footer padding",
"value": "20px horizontal mobile / 24px md; 16px vertical"
},
{
"property": "Close target",
"value": "44 × 44px"
},
{
"property": "Close glyph",
"value": "24 × 24px"
},
{
"property": "Close glyph inset",
"value": "16px from top and logical end",
"notes": "Shared with Dialog; the target does not determine header height."
}
],
"rules": [
"Compose regions only inside ModalPanel.",
"Use the shared overlay header and close-control pattern.",
"Hover strengthens the icon without drawing a border; keyboard focus retains the standard outline.",
"Keep a single scrollable body between fixed header and footer.",
"Use alertdialog role only for consequential confirmations."
],
"responsiveBehavior": [
"Aligns near the top on small screens and centers from sm upward.",
"Body scrolls within a viewport-bounded panel."
]
},
"designTokens": [
{
"token": "--color-overlay",
"purpose": "Backdrop."
},
{
"token": "--color-surface / --color-border",
"purpose": "Panel and dividers through Surface."
},
{
"token": "--color-text / --color-text2",
"purpose": "Heading and description."
},
{
"token": "--radius-md",
"purpose": "Panel radius."
}
],
"stateDefinitions": [
{
"name": "closed",
"trigger": "ModalOverlay is not rendered.",
"visual": "No modal UI.",
"behavior": "Page owns focus and scrolling."
},
{
"name": "open",
"trigger": "ModalOverlay is mounted.",
"visual": "Blurred overlay and panel are visible.",
"behavior": "Headless UI traps focus, locks background interaction, and handles Escape."
},
{
"name": "nested",
"trigger": "A modal is opened from another focus scope.",
"visual": "Higher-level modal remains visually subordinate.",
"behavior": "Use sparingly and verify focus restoration at each level.",
"accessibility": "Every dialog must retain a unique name."
},
{
"name": "focus-visible",
"trigger": "Keyboard focus reaches a control.",
"visual": "The focused child component supplies its standard ring.",
"behavior": "Tab remains within the active dialog."
}
],
"keyboard": [
{
"key": "Escape",
"action": "Requests onClose when supplied."
},
{
"key": "Tab / Shift+Tab",
"action": "Cycles through focusable modal content."
},
{
"key": "Enter / Space",
"action": "Activates the focused control."
}
],
"accessibilitySpec": {
"semantics": "Headless UI Dialog; Header uses DialogTitle and Description, and alertdialog is supported.",
"accessibleName": "ModalHeader heading supplies the name; description supplies supporting text.",
"requirements": [
"Always include ModalHeader with a meaningful heading or provide an equivalent Headless UI title.",
"Supply an onClose control unless the operation intentionally prevents dismissal.",
"Keep footer action order and labels explicit."
]
},
"implementation": {
"importStatement": "import { ModalOverlay, ModalPanel, ModalHeader, ModalBody, ModalFooter } from '@ai-created/ui';",
"clientComponent": true,
"notes": [
"Render ModalOverlay conditionally; it is always open while mounted.",
"onClose is optional because ConfirmDialog can suppress dismissal while loading.",
"closeOnBackdrop affects pointer backdrop dismissal only.",
"ModalBody scroll defaults to true."
]
},
"guidance": {
"dos": [
"Use for rich but bounded application tasks.",
"Keep the primary action in the footer and close action in the header."
],
"donts": [
"Do not mount without a panel and title.",
"Do not place essential page navigation inside a modal."
]
},
"testing": {
"unit": [
"Maps the shared Dialog panel sizes and every region option.",
"Optional onClose behavior is deterministic."
],
"interaction": [
"Escape, backdrop setting, 44px close button, focus trap, body scrolling, and restoration work."
],
"accessibility": [
"Dialog naming, description, role, focus order, and inert background are valid."
],
"visual": [
"Capture sizes, mobile top alignment, desktop centering, overflow, header/footer variants, and themes."
]
},
"relatedComponents": [
"dialog",
"confirm-dialog",
"surface",
"button"
],
"controls": {
"open": {
"type": "boolean",
"label": "Open",
"defaultValue": false
},
"size": {
"type": "select",
"label": "Size",
"defaultValue": "lg",
"options": [
"sm",
"md",
"lg",
"xl"
]
},
"closeOnBackdrop": {
"type": "boolean",
"label": "Backdrop closes",
"defaultValue": true
},
"scroll": {
"type": "boolean",
"label": "Scrollable body",
"defaultValue": true
}
},
"construction": {
"asset": {
"kind": "component",
"figmaName": "Components/Overlays/Modal",
"localName": "Modal family",
"canvasApplicability": "Publish a composable overlay component with panel, header, body, and footer slots."
},
"autoLayout": {
"applicable": true,
"direction": "vertical",
"gap": "0px between regions",
"padding": "16px viewport inset; region padding owned by subcomponents; close target pinned 6px from the header top and logical end",
"alignment": "Stretch",
"wrap": "Region content wraps",
"notes": []
},
"resizing": {
"applicable": true,
"width": "fill",
"height": "content-controlled",
"minWidth": "280px",
"maxWidth": "sm 384px; md 512px; lg 672px; xl 896px",
"minHeight": "Content controlled",
"maxHeight": "Viewport minus 32px",
"overflow": "auto",
"notes": []
},
"exposedProperties": [
{
"name": "open",
"label": "Open",
"type": "boolean",
"required": false,
"defaultValue": false,
"codeMapping": "Conditional rendering of ModalOverlay"
},
{
"name": "size",
"label": "Size",
"type": "variant",
"required": false,
"defaultValue": "lg",
"options": [
"sm",
"md",
"lg",
"xl"
],
"codeMapping": "ModalPanel.size"
},
{
"name": "closeOnBackdrop",
"label": "Backdrop closes",
"type": "boolean",
"required": false,
"defaultValue": true,
"codeMapping": "ModalOverlay.closeOnBackdrop"
},
{
"name": "scroll",
"label": "Scrollable body",
"type": "boolean",
"required": false,
"defaultValue": true,
"codeMapping": "ModalBody.scroll"
},
{
"name": "heading",
"label": "Heading",
"type": "text",
"required": true,
"defaultValue": "Settings",
"codeMapping": "ModalHeader.heading"
},
{
"name": "description",
"label": "Description",
"type": "text",
"required": false,
"defaultValue": null,
"codeMapping": "ModalHeader.description"
},
{
"name": "body",
"label": "Body",
"type": "slot",
"required": true,
"defaultValue": null,
"codeMapping": "ModalBody children"
},
{
"name": "footer",
"label": "Footer",
"type": "slot",
"required": false,
"defaultValue": null,
"codeMapping": "ModalFooter children"
}
],
"nestedAssets": [
{
"name": "ModalOverlay",
"kind": "subcomponent",
"required": true,
"description": "Backdrop, semantics, dismissal, and focus boundary.",
"codeMapping": "ModalOverlay"
},
{
"name": "ModalPanel",
"kind": "subcomponent",
"required": true,
"description": "Sized modal surface.",
"codeMapping": "ModalPanel"
},
{
"name": "ModalHeader",
"kind": "subcomponent",
"required": true,
"description": "Heading, optional description, and close control.",
"codeMapping": "ModalHeader"
},
{
"name": "ModalBody",
"kind": "subcomponent",
"required": true,
"description": "Primary scroll region.",
"codeMapping": "ModalBody"
},
{
"name": "ModalFooter",
"kind": "subcomponent",
"required": false,
"description": "Action region.",
"codeMapping": "ModalFooter"
}
],
"contentLimits": [
{
"target": "Heading",
"limit": "One line preferred, maximum two lines",
"overflowBehavior": "Wrap; never truncate.",
"rationale": "The modal task should remain clear."
},
{
"target": "Footer actions",
"limit": "One primary and up to two secondary actions",
"overflowBehavior": "Move tertiary actions into body content.",
"rationale": "A contained decision needs a clear hierarchy."
},
{
"target": "Body",
"limit": "One focused workflow",
"overflowBehavior": "Use a full page for broad or deeply nested tasks.",
"rationale": "Modal interruption cost rises with complexity."
}
],
"localization": {
"translatable": [
"Heading",
"Description",
"Body",
"Action labels"
],
"rtlBehavior": [
"Header close action and footer alignment use logical sides.",
"Content follows locale direction."
],
"stressCases": [
"Test long action labels.",
"Test body overflow and 200% zoom.",
"Test nested directional form controls."
]
},
"responsive": {
"strategy": "Panel is viewport-constrained and body may scroll.",
"breakpoints": [
"No internal breakpoint"
],
"behavior": [
"Maintain 16px viewport inset.",
"On product-defined small screens, a full-height presentation may be composed outside this primitive."
]
},
"limitations": {
"figma": [
"Figma nesting demonstrates structure but not portal, focus, inert background, or scroll-lock behavior."
],
"code": [
"Consumers own whether the ModalOverlay is mounted; this family has no open prop itself."
],
"notApplicable": []
},
"governance": {
"status": "stable",
"ownerRole": "Design systems overlay primitive owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/components/Modal.tsx",
"changePolicy": [
"Subcomponent contracts and dismissal changes require overlay accessibility review.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
},
{
"id": "confirm-dialog",
"name": "ConfirmDialog",
"category": "Overlays",
"purpose": "Confirms a consequential action with explicit cancel and confirm controls.",
"useWhen": [
"Destructive or irreversible actions"
],
"avoidWhen": [
"Routine actions that do not need interruption"
],
"api": [
{
"prop": "open",
"type": "boolean",
"defaultValue": "required",
"description": "Whether the dialog is shown."
},
{
"prop": "onConfirm",
"type": "() => void",
"defaultValue": "required",
"description": "Confirm callback."
},
{
"prop": "onCancel",
"type": "() => void",
"defaultValue": "required",
"description": "Cancel callback."
},
{
"prop": "title",
"type": "string",
"defaultValue": "required",
"description": "Dialog heading."
},
{
"prop": "description",
"type": "ReactNode",
"defaultValue": "undefined",
"description": "Supporting explanation."
},
{
"prop": "confirmLabel",
"type": "string",
"defaultValue": "Confirm",
"description": "Confirm button label."
},
{
"prop": "cancelLabel",
"type": "string",
"defaultValue": "Cancel",
"description": "Cancel button label."
},
{
"prop": "destructive",
"type": "boolean",
"defaultValue": "false",
"description": "Uses destructive styling."
},
{
"prop": "loading",
"type": "boolean",
"defaultValue": "false",
"description": "Disables dismissal while working."
},
{
"prop": "loadingLabel",
"type": "string",
"defaultValue": "Working…",
"description": "Busy button label."
}
],
"states": [
"closed",
"open",
"loading"
],
"accessibility": [
"Uses alertdialog semantics.",
"Dismissal is disabled while loading."
],
"composition": [
"Use for a single consequential action with a clear description."
],
"code": "
",
"slug": "confirm-dialog",
"summary": "A constrained alert dialog for confirming one consequential or irreversible action.",
"sourcePath": "src/components/ConfirmDialog.tsx",
"packageExports": [
"ConfirmDialog",
"ConfirmDialogProps"
],
"anatomy": [
{
"name": "Alert dialog",
"description": "Small Modal composition with alertdialog semantics.",
"required": true
},
{
"name": "Title",
"description": "Names the exact action under confirmation.",
"required": true
},
{
"name": "Description",
"description": "Optional consequence and scope explanation.",
"required": false
},
{
"name": "Cancel action",
"description": "Safe dismissal path.",
"required": true,
"semanticElement": "button"
},
{
"name": "Confirm action",
"description": "Executes the consequential operation.",
"required": true,
"semanticElement": "button"
}
],
"visualSpec": {
"measurements": [
{
"property": "Panel width",
"value": "max 384px"
},
{
"property": "Footer action gap",
"value": "12px"
},
{
"property": "Header padding",
"value": "20px horizontal mobile / 24px md; 12px vertical"
},
{
"property": "Body/footer padding",
"value": "20px horizontal mobile / 24px md; 16px vertical"
},
{
"property": "Close target",
"value": "44 × 44px"
},
{
"property": "Close glyph",
"value": "24 × 24px"
},
{
"property": "Close glyph inset",
"value": "16px from top and logical end",
"notes": "Inherited from the shared overlay header while the dialog is dismissible."
}
],
"rules": [
"Name the specific object and action.",
"Place Cancel before Confirm in the footer.",
"Use destructive styling only for destructive consequences."
]
},
"designTokens": [
{
"token": "--color-overlay",
"purpose": "Modal backdrop."
},
{
"token": "--color-surface / --color-border",
"purpose": "Panel and dividers."
},
{
"token": "--color-action-primary",
"purpose": "Standard confirmation."
},
{
"token": "--color-action-destructive",
"purpose": "Destructive confirmation."
},
{
"token": "--color-on-action",
"purpose": "Filled action foreground."
},
{
"token": "--color-text / --color-text2",
"purpose": "Title and description."
}
],
"stateDefinitions": [
{
"name": "closed",
"trigger": "open is false.",
"visual": "Nothing is rendered.",
"behavior": "No focus scope exists."
},
{
"name": "open",
"trigger": "open is true.",
"visual": "Small alert dialog with cancel and confirm actions.",
"behavior": "Focus is trapped; dismissal calls onCancel."
},
{
"name": "loading",
"trigger": "loading is true.",
"visual": "Both actions are disabled and confirm label becomes loadingLabel.",
"behavior": "Escape, backdrop, header close, cancel, and confirm activation are blocked.",
"accessibility": "Disabled buttons expose unavailability; the label communicates work in progress."
}
],
"keyboard": [
{
"key": "Escape",
"action": "Cancels and closes.",
"condition": "Only while not loading."
},
{
"key": "Tab / Shift+Tab",
"action": "Moves between available actions within the dialog."
},
{
"key": "Enter / Space",
"action": "Activates the focused cancel or confirm button.",
"condition": "Only while not loading."
}
],
"accessibilitySpec": {
"semantics": "Headless UI alertdialog composed from Modal primitives.",
"accessibleName": "Required title names the alert dialog; optional Description is associated by Headless UI.",
"requirements": [
"Initial focus should land on the safest useful control for the context; verify Headless UI behavior in integration.",
"Explain irreversible consequences before the action.",
"Do not rely on destructive color; button text must be specific.",
"Expose completion or failure after loading ends."
]
},
"implementation": {
"importStatement": "import { ConfirmDialog } from '@ai-created/ui';",
"clientComponent": true,
"notes": [
"Returns null while closed.",
"destructive changes the confirm visual variant; it does not alter semantics.",
"loading suppresses every dismissal callback and action.",
"The parent owns async state and closes on success."
]
},
"guidance": {
"dos": [
"Reserve confirmation for meaningful consequences.",
"Use labels such as Delete project instead of Confirm."
],
"donts": [
"Do not interrupt routine reversible actions.",
"Do not allow the dialog to close while its operation is unresolved."
]
},
"testing": {
"unit": [
"Closed returns null; defaults and destructive variant map correctly.",
"Loading disables all dismissal paths and changes the label."
],
"interaction": [
"Cancel, confirm, Escape, backdrop, focus trap, loading, and restoration work."
],
"accessibility": [
"Alertdialog is named/described and actions have specific names and correct disabled state."
],
"visual": [
"Capture regular/destructive, description absent/present, loading, long labels, and themes."
]
},
"relatedComponents": [
"modal",
"dialog",
"button"
],
"controls": {
"open": {
"type": "boolean",
"label": "Open",
"defaultValue": false
},
"destructive": {
"type": "boolean",
"label": "Destructive",
"defaultValue": true
},
"loading": {
"type": "boolean",
"label": "Loading",
"defaultValue": false
},
"title": {
"type": "text",
"label": "Title",
"defaultValue": "Delete project?"
}
},
"construction": {
"asset": {
"kind": "component",
"figmaName": "Components/Overlays/Confirm dialog",
"localName": "ConfirmDialog",
"canvasApplicability": "Publish standard, destructive, and loading variants with localized copy properties."
},
"autoLayout": {
"applicable": true,
"direction": "vertical",
"gap": "0px regions; 12px between footer actions",
"padding": "16px viewport inset; panel region padding",
"alignment": "Stretch with actions aligned to logical end",
"wrap": "Actions may wrap at narrow widths",
"notes": []
},
"resizing": {
"applicable": true,
"width": "fill",
"height": "hug",
"minWidth": "280px",
"maxWidth": "384px",
"minHeight": "Content controlled",
"maxHeight": "Viewport minus 32px",
"overflow": "auto",
"notes": []
},
"exposedProperties": [
{
"name": "open",
"label": "Open",
"type": "boolean",
"required": true,
"defaultValue": false,
"codeMapping": "open"
},
{
"name": "destructive",
"label": "Destructive",
"type": "boolean",
"required": false,
"defaultValue": false,
"codeMapping": "destructive"
},
{
"name": "loading",
"label": "Loading",
"type": "boolean",
"required": false,
"defaultValue": false,
"codeMapping": "loading"
},
{
"name": "title",
"label": "Title",
"type": "text",
"required": true,
"defaultValue": "Confirm action?",
"codeMapping": "title"
},
{
"name": "description",
"label": "Description",
"type": "slot",
"required": false,
"defaultValue": null,
"codeMapping": "description"
},
{
"name": "confirmLabel",
"label": "Confirm label",
"type": "text",
"required": false,
"defaultValue": "Confirm",
"codeMapping": "confirmLabel"
},
{
"name": "cancelLabel",
"label": "Cancel label",
"type": "text",
"required": false,
"defaultValue": "Cancel",
"codeMapping": "cancelLabel"
},
{
"name": "loadingLabel",
"label": "Loading label",
"type": "text",
"required": false,
"defaultValue": "Working...",
"codeMapping": "loadingLabel"
}
],
"nestedAssets": [
{
"name": "Modal family",
"kind": "subcomponent",
"required": true,
"description": "Alert dialog overlay, panel, header, body, and footer.",
"codeMapping": "ModalOverlay and subcomponents"
},
{
"name": "Cancel action",
"kind": "subcomponent",
"required": true,
"description": "Secondary dismissal action.",
"codeMapping": "Button"
},
{
"name": "Confirm action",
"kind": "subcomponent",
"required": true,
"description": "Consequential action and loading state.",
"codeMapping": "Button"
}
],
"contentLimits": [
{
"target": "Title",
"limit": "A direct question, maximum two lines",
"overflowBehavior": "Wrap and revise if longer.",
"rationale": "The exact decision must be obvious."
},
{
"target": "Description",
"limit": "One short paragraph describing consequence",
"overflowBehavior": "Move detailed policy outside the dialog.",
"rationale": "Users need enough context to decide without overload."
},
{
"target": "Action labels",
"limit": "Specific verbs, recommended maximum 24 characters",
"overflowBehavior": "Stack actions if localization requires it.",
"rationale": "Specific labels reduce confirmation errors."
}
],
"localization": {
"translatable": [
"Title",
"Description",
"Confirm, cancel, and loading labels"
],
"rtlBehavior": [
"Footer actions follow product locale conventions while preserving safe action hierarchy.",
"Directional icons, if added, mirror."
],
"stressCases": [
"Test long destructive verbs.",
"Test loading announcement and blocked dismissal.",
"Test 200% zoom."
]
},
"responsive": {
"strategy": "Small modal width with viewport inset.",
"breakpoints": [
"Parent-selected narrow breakpoint"
],
"behavior": [
"Allow footer actions to stack full width in a product composition when labels no longer fit.",
"Do not reorder safe and destructive actions between widths."
]
},
"limitations": {
"figma": [
"Figma loading variants cannot validate blocked backdrop and Escape dismissal."
],
"code": [
"The consumer owns asynchronous completion and must clear loading or close the dialog."
],
"notApplicable": []
},
"governance": {
"status": "stable",
"ownerRole": "Design systems safety pattern owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/components/ConfirmDialog.tsx",
"changePolicy": [
"Destructive defaults or action ordering changes require safety, content, and accessibility review.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
},
{
"id": "tooltip",
"name": "Tooltip",
"category": "Overlays",
"purpose": "Provides brief supplemental information for a trigger.",
"useWhen": [
"Clarifying unfamiliar icons or controls"
],
"avoidWhen": [
"Essential instructions",
"Long or interactive content"
],
"api": [
{
"prop": "content",
"type": "string",
"defaultValue": "required",
"description": "Tooltip text."
},
{
"prop": "position",
"type": "TooltipPosition",
"defaultValue": "top",
"description": "top, bottom, left, or right."
},
{
"prop": "delay",
"type": "number",
"defaultValue": "300",
"description": "Show delay in milliseconds."
},
{
"prop": "children",
"type": "ReactElement",
"defaultValue": "required",
"description": "Trigger element."
},
{
"prop": "className",
"type": "string",
"defaultValue": "undefined",
"description": "Additional tooltip classes."
}
],
"states": [
"hidden",
"visible",
"focused",
"touch-visible"
],
"accessibility": [
"Adds aria-describedby while visible.",
"Keep essential information outside the tooltip."
],
"composition": [
"Wrap one focusable trigger."
],
"code": "
",
"slug": "tooltip",
"summary": "A brief, non-interactive description shown from pointer, focus, or touch.",
"sourcePath": "src/components/Tooltip.tsx",
"packageExports": [
"Tooltip",
"TooltipProps",
"TooltipPosition"
],
"anatomy": [
{
"name": "Wrapper",
"description": "Inline trigger measurement context.",
"required": true,
"semanticElement": "span"
},
{
"name": "Trigger",
"description": "Exactly one cloned focusable element.",
"required": true
},
{
"name": "Tooltip bubble",
"description": "Portalled, viewport-positioned description associated while visible.",
"required": true,
"semanticElement": "[role=tooltip]"
}
],
"visualSpec": {
"measurements": [
{
"property": "Bubble padding",
"value": "12px horizontal / 6px vertical"
},
{
"property": "Trigger offset",
"value": "8px"
},
{
"property": "Viewport inset",
"value": "8px minimum"
},
{
"property": "Maximum width",
"value": "240px"
},
{
"property": "Radius",
"value": "6px"
},
{
"property": "Entrance",
"value": "200ms fade"
}
],
"rules": [
"Keep content brief, plain text, and non-interactive.",
"Preferred placement flips when its opposite side has available space and clamps to the viewport.",
"Do not hide essential instructions in the tooltip."
]
},
"designTokens": [
{
"token": "--color-surface",
"purpose": "Bubble background."
},
{
"token": "--color-border",
"purpose": "Bubble border."
},
{
"token": "--color-text2",
"purpose": "Tooltip text."
},
{
"token": "--radius-md",
"purpose": "Bubble radius."
},
{
"token": "--shadow-elevation-medium / --layer-tooltip",
"purpose": "Portalled elevation and stacking."
},
{
"token": "--motion-fast",
"purpose": "Entrance fade."
}
],
"stateDefinitions": [
{
"name": "hidden",
"trigger": "No active pointer, focus, or toggled touch.",
"visual": "Bubble is not mounted.",
"behavior": "Trigger retains its original aria-describedby."
},
{
"name": "visible",
"trigger": "Pointer hover remains for delay milliseconds.",
"visual": "Bubble appears at the resolved viewport position.",
"behavior": "Pointer may cross onto the bubble without dismissing it; leaving both hides after a short bridge delay.",
"accessibility": "Tooltip id is appended to aria-describedby while visible."
},
{
"name": "focused",
"trigger": "Trigger receives focus for delay milliseconds.",
"visual": "Same bubble as hover.",
"behavior": "Blur hides it."
},
{
"name": "touch-visible",
"trigger": "Trigger receives touchstart.",
"visual": "Bubble toggles immediately.",
"behavior": "Another touch or outside touch hides it."
}
],
"keyboard": [
{
"key": "Tab / Shift+Tab",
"action": "Focuses the child trigger; tooltip appears after delay."
},
{
"key": "Escape",
"action": "Dismisses the tooltip without moving focus."
}
],
"accessibilitySpec": {
"semantics": "role=tooltip associated through aria-describedby only while visible.",
"accessibleName": "content provides the supplemental description; the trigger still needs its own accessible name.",
"requirements": [
"Wrap exactly one focusable trigger.",
"Preserve existing trigger event handlers and aria-describedby; the component composes them.",
"Keep content non-interactive and supplemental.",
"Do not use the tooltip as the accessible name of an icon button."
]
},
"implementation": {
"importStatement": "import { Tooltip } from '@ai-created/ui';",
"clientComponent": true,
"notes": [
"The child element is cloned to compose hover, focus, blur, and touch handlers.",
"Show and hover-bridge timeouts are cleared on hide and unmount.",
"The bubble portals to document.body, flips to the opposite side when needed, clamps to the viewport, and tracks scroll/resize.",
"Escape and outside touch listeners exist only while visible."
]
},
"guidance": {
"dos": [
"Use to explain an unfamiliar icon or compact control.",
"Keep one short sentence or phrase."
],
"donts": [
"Do not put links, buttons, or form fields inside.",
"Do not repeat a visible label verbatim without adding value."
]
},
"testing": {
"unit": [
"Composes existing child handlers and aria-describedby.",
"Clears timers and temporary listeners."
],
"interaction": [
"Hover/focus delay, pointer travel onto the bubble, Escape, leave/blur, touch toggle, outside touch, flip, clamp, scroll, and resize behave correctly."
],
"accessibility": [
"Role, id relationship, trigger name, Escape dismissal, and keyboard discoverability are valid."
],
"visual": [
"Capture all positions, viewport edges, wrapping at max width, focus/hover visibility, and themes."
]
},
"relatedComponents": [
"button"
],
"controls": {
"position": {
"type": "select",
"label": "Position",
"defaultValue": "top",
"options": [
"top",
"bottom",
"left",
"right"
]
},
"delay": {
"type": "number",
"label": "Delay",
"defaultValue": 300,
"min": 0,
"max": 1000,
"step": 50,
"unit": "ms"
},
"content": {
"type": "text",
"label": "Content",
"defaultValue": "Copy link"
}
},
"construction": {
"asset": {
"kind": "component",
"figmaName": "Components/Overlays/Tooltip",
"localName": "Tooltip",
"canvasApplicability": "Publish position and visibility variants attached to an example trigger."
},
"autoLayout": {
"applicable": true,
"direction": "horizontal",
"gap": "0px",
"padding": "6px 12px",
"alignment": "Center",
"wrap": "Text wraps up to maximum width",
"notes": []
},
"resizing": {
"applicable": true,
"width": "hug",
"height": "hug",
"minWidth": "Content width",
"maxWidth": "240px",
"minHeight": "Content controlled",
"maxHeight": "Content controlled",
"overflow": "visible",
"notes": []
},
"exposedProperties": [
{
"name": "content",
"label": "Content",
"type": "text",
"required": true,
"defaultValue": "Helpful information",
"codeMapping": "content"
},
{
"name": "position",
"label": "Position",
"type": "variant",
"required": false,
"defaultValue": "top",
"options": [
"top",
"bottom",
"left",
"right"
],
"codeMapping": "position"
},
{
"name": "delay",
"label": "Delay",
"type": "number",
"required": false,
"defaultValue": 300,
"codeMapping": "delay"
},
{
"name": "visible",
"label": "Visible preview",
"type": "boolean",
"required": false,
"defaultValue": true,
"codeMapping": "Internal interaction state; no public prop"
},
{
"name": "trigger",
"label": "Trigger",
"type": "instance-swap",
"required": true,
"defaultValue": null,
"codeMapping": "children"
}
],
"nestedAssets": [
{
"name": "Trigger",
"kind": "slot",
"required": true,
"description": "One focusable element that owns described-by state.",
"codeMapping": "children"
},
{
"name": "Tooltip bubble",
"kind": "primitive",
"required": true,
"description": "Positioned supplemental text.",
"codeMapping": "
"
}
],
"contentLimits": [
{
"target": "Content",
"limit": "One short sentence, maximum about 120 characters",
"overflowBehavior": "Wrap up to 240px; move longer guidance into persistent UI.",
"rationale": "Tooltips are supplemental and transient."
},
{
"target": "Children",
"limit": "Exactly one focusable trigger",
"overflowBehavior": "Wrap compound visuals in one semantic control.",
"rationale": "Focus and described-by must have one owner."
}
],
"localization": {
"translatable": [
"Content"
],
"rtlBehavior": [
"Position uses physical sides today; choose the appropriate side for the layout direction.",
"Text follows locale direction."
],
"stressCases": [
"Test 240px maximum width.",
"Test touch, keyboard, and pointer access with translated text."
]
},
"responsive": {
"strategy": "Bubble hugs content, portals to the document, flips when the opposite side fits, and clamps within an 8px viewport inset.",
"breakpoints": [
"No internal breakpoint"
],
"behavior": [
"Preferred physical side remains consumer-selected.",
"Do not depend on tooltip access for essential mobile instructions."
]
},
"limitations": {
"figma": [
"Figma hover prototypes do not cover delayed focus, pointer travel, Escape, touch toggling, outside touch, viewport collision, or aria-describedby."
],
"code": [
"Keep content supplemental, plain text, and non-interactive."
],
"notApplicable": []
},
"governance": {
"status": "stable",
"ownerRole": "Design systems overlay primitive owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/components/Tooltip.tsx",
"changePolicy": [
"Timing or trigger-event changes require input-modality and accessibility testing.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
},
{
"id": "themed-hero-image",
"name": "ThemedHeroImage",
"category": "Theme & media",
"purpose": "Displays a decorative hero image that adapts to the active theme.",
"useWhen": [
"Large decorative hero backgrounds"
],
"avoidWhen": [
"Content images that need an alt description"
],
"api": [
{
"prop": "darkSrc",
"type": "string",
"defaultValue": "required",
"description": "Dark-theme image source."
},
{
"prop": "lightSrc",
"type": "string",
"defaultValue": "undefined",
"description": "Optional light-theme source."
},
{
"prop": "overlay",
"type": "default | strong | soft | none",
"defaultValue": "default",
"description": "Overlay treatment."
},
{
"prop": "priority",
"type": "boolean",
"defaultValue": "false",
"description": "Next Image priority loading."
},
{
"prop": "quality",
"type": "number",
"defaultValue": "85",
"description": "Image quality."
},
{
"prop": "sizes",
"type": "string",
"defaultValue": "100vw",
"description": "Responsive image sizes."
},
{
"prop": "objectPosition",
"type": "string",
"defaultValue": "undefined",
"description": "Image object position."
},
{
"prop": "fadeTop",
"type": "boolean",
"defaultValue": "false",
"description": "Top fade."
},
{
"prop": "fadeBottom",
"type": "boolean",
"defaultValue": "false",
"description": "Bottom fade."
},
{
"prop": "blendLight",
"type": "boolean",
"defaultValue": "false",
"description": "Light-theme blend."
}
],
"states": [
"dark theme",
"light theme"
],
"accessibility": [
"Image is intentionally decorative with empty alt text."
],
"composition": [
"Place behind hero content in a positioned container."
],
"code": "",
"slug": "themed-hero-image",
"summary": "A decorative, theme-aware hero background with coordinated overlays, fades, and optional light blending.",
"sourcePath": "src/components/ThemedHeroImage.tsx",
"packageExports": [
"ThemedHeroImage",
"ThemedHeroImageProps"
],
"anatomy": [
{
"name": "Positioning root",
"description": "Absolute full-bleed media container.",
"required": true,
"semanticElement": "div"
},
{
"name": "Dark image",
"description": "Required default decorative image.",
"required": true
},
{
"name": "Light image",
"description": "Optional cross-faded light-theme image.",
"required": false
},
{
"name": "Overlay",
"description": "Theme-aware contrast layer.",
"required": false
},
{
"name": "Top/bottom fades",
"description": "Optional gradients blending into page background.",
"required": false
}
],
"visualSpec": {
"measurements": [
{
"property": "Bounds",
"value": "absolute inset 0"
},
{
"property": "Image fit",
"value": "cover"
},
{
"property": "Theme cross-fade",
"value": "500ms during theme transitions"
},
{
"property": "Fade depth",
"value": "one third of container height"
},
{
"property": "Default quality",
"value": "85"
}
],
"rules": [
"Parent must establish positioning and an explicit height.",
"Maintain sufficient text contrast over both images.",
"Use only for decorative imagery; content images require semantic Image usage."
],
"responsiveBehavior": [
"sizes defaults to 100vw and should be narrowed when the image is not full viewport width.",
"objectPosition controls art-direction focus as the container crops."
]
},
"designTokens": [
{
"token": "--hero-overlay-default / strong / soft",
"purpose": "Theme-specific contrast overlays."
},
{
"token": "--hero-image-dark-opacity / --hero-image-light-opacity",
"purpose": "Theme image swap."
},
{
"token": "--color-bg",
"purpose": "Top and bottom fade destination."
},
{
"token": "--motion-slow",
"purpose": "Theme cross-fade."
}
],
"stateDefinitions": [
{
"name": "dark theme",
"trigger": "Root does not have light class.",
"visual": "Dark source is opaque; optional light source is transparent; dark overlay values apply.",
"behavior": "Image remains decorative."
},
{
"name": "light theme",
"trigger": "Root has light class.",
"visual": "Optional light source is opaque and dark source transparent; warm overlay values apply.",
"behavior": "blendLight can multiply the image into the light surface."
}
],
"keyboard": [],
"accessibilitySpec": {
"semantics": "Next Image elements use empty alt and aria-hidden; overlays are plain decorative divs.",
"accessibleName": "No accessible name by design.",
"requirements": [
"Use only when the image conveys no information that is absent from nearby text.",
"Do not put interactive content inside the component.",
"Verify overlaid text contrast independently in both themes and crop sizes."
]
},
"implementation": {
"importStatement": "import { ThemedHeroImage } from '@ai-created/ui';",
"clientComponent": false,
"notes": [
"Requires Next.js Image configuration for external sources.",
"priority applies only to the dark image; use it for an above-the-fold hero.",
"If lightSrc is absent, the dark image remains fully visible in both themes.",
"overlay none deliberately renders no overlay node."
]
},
"guidance": {
"dos": [
"Art-direct dark and light sources for comparable subject placement.",
"Set accurate sizes and use priority only above the fold."
],
"donts": [
"Do not use for product screenshots or informative charts.",
"Do not assume an overlay guarantees accessible contrast."
]
},
"testing": {
"unit": [
"Maps overlay, fades, blend, sizes, quality, priority, and object position.",
"Renders one or two images as configured."
],
"interaction": [
"Theme class changes swap opacity without affecting layout."
],
"accessibility": [
"Images remain hidden from the accessibility tree and overlaid copy passes contrast."
],
"visual": [
"Capture dark/light, every overlay, fades, blend, and representative crop ratios."
]
},
"relatedComponents": [
"theme",
"surface"
],
"controls": {
"overlay": {
"type": "select",
"label": "Overlay",
"defaultValue": "default",
"options": [
"default",
"strong",
"soft",
"none"
]
},
"fadeTop": {
"type": "boolean",
"label": "Top fade",
"defaultValue": false
},
"fadeBottom": {
"type": "boolean",
"label": "Bottom fade",
"defaultValue": false
},
"blendLight": {
"type": "boolean",
"label": "Light blend",
"defaultValue": false
}
},
"construction": {
"asset": {
"kind": "component",
"figmaName": "Components/Media/Themed hero image",
"localName": "ThemedHeroImage",
"canvasApplicability": "Publish a frame-filling media component with dark and light image swaps and overlay variants."
},
"autoLayout": {
"applicable": true,
"direction": "overlay",
"gap": "0px",
"padding": "0px",
"alignment": "Stretch to all frame edges",
"wrap": "Layers overlap",
"notes": [
"Layer order is media, theme alternative, overlay, top fade, then bottom fade."
]
},
"resizing": {
"applicable": true,
"width": "fill",
"height": "fill",
"minWidth": "Parent controlled",
"maxWidth": "Parent controlled",
"minHeight": "Parent controlled",
"maxHeight": "Parent controlled",
"overflow": "clip",
"notes": [
"The parent must be positioned and have an explicit or content-derived height."
]
},
"exposedProperties": [
{
"name": "darkSrc",
"label": "Dark image",
"type": "instance-swap",
"required": true,
"defaultValue": null,
"codeMapping": "darkSrc"
},
{
"name": "lightSrc",
"label": "Light image",
"type": "instance-swap",
"required": false,
"defaultValue": null,
"codeMapping": "lightSrc"
},
{
"name": "overlay",
"label": "Overlay",
"type": "variant",
"required": false,
"defaultValue": "default",
"options": [
"default",
"strong",
"soft",
"none"
],
"codeMapping": "overlay"
},
{
"name": "fadeTop",
"label": "Top fade",
"type": "boolean",
"required": false,
"defaultValue": false,
"codeMapping": "fadeTop"
},
{
"name": "fadeBottom",
"label": "Bottom fade",
"type": "boolean",
"required": false,
"defaultValue": false,
"codeMapping": "fadeBottom"
},
{
"name": "blendLight",
"label": "Light blend",
"type": "boolean",
"required": false,
"defaultValue": false,
"codeMapping": "blendLight"
},
{
"name": "objectPosition",
"label": "Focal point",
"type": "text",
"required": false,
"defaultValue": "center",
"codeMapping": "objectPosition"
}
],
"nestedAssets": [
{
"name": "Dark media",
"kind": "slot",
"required": true,
"description": "Required decorative image.",
"codeMapping": "darkSrc"
},
{
"name": "Light media",
"kind": "slot",
"required": false,
"description": "Optional light-theme image.",
"codeMapping": "lightSrc"
},
{
"name": "Overlay",
"kind": "primitive",
"required": false,
"description": "Theme token overlay treatment.",
"codeMapping": "Internal overlay layer"
},
{
"name": "Fades",
"kind": "primitive",
"required": false,
"description": "Top and bottom content-legibility fades.",
"codeMapping": "Internal fade layers"
}
],
"contentLimits": [
{
"target": "Media role",
"limit": "Decorative hero imagery only",
"overflowBehavior": "Use a semantic image component for meaningful content.",
"rationale": "The implementation always uses empty alt text."
},
{
"target": "File weight",
"limit": "Use the smallest source that remains sharp at rendered sizes",
"overflowBehavior": "Create responsive optimized assets.",
"rationale": "Hero media has high performance impact."
}
],
"localization": {
"translatable": [],
"rtlBehavior": [
"Image framing must preserve important subjects for both directions.",
"Do not place baked-in text in the source image."
],
"stressCases": [
"Review focal points with right-to-left copy placement.",
"Test dark and light assets behind twice-length headings."
]
},
"responsive": {
"strategy": "Absolute fill with object-cover.",
"breakpoints": [
"Use sizes to describe actual layout breakpoints"
],
"behavior": [
"Set a focal point that survives crop changes.",
"Parent owns aspect ratio and minimum content height.",
"Provide an accurate sizes value for image selection."
]
},
"limitations": {
"figma": [
"Figma fills do not validate Next Image loading, responsive source selection, or blend behavior."
],
"code": [
"Always decorative; do not use for content that needs alternative text."
],
"notApplicable": []
},
"governance": {
"status": "stable",
"ownerRole": "Design systems media foundations owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/components/ThemedHeroImage.tsx",
"changePolicy": [
"Overlay and blend changes require contrast review against representative hero copy.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
},
{
"id": "theme",
"name": "ThemeProvider / useTheme / ThemeToggle",
"category": "Theme & media",
"purpose": "Controls dark/light mode and the active accessible accent scheme.",
"useWhen": [
"Applications supporting theme and accent preferences"
],
"avoidWhen": [
"Components that should not own global theme state"
],
"api": [
{
"prop": "ThemeProvider.children",
"type": "ReactNode",
"defaultValue": "required",
"description": "Application subtree."
},
{
"prop": "ThemeProvider.accent",
"type": "Accent",
"defaultValue": "undefined",
"description": "Controlled, fixed accent; wins over storage and defaults."
},
{
"prop": "ThemeProvider.defaultAccent",
"type": "Accent",
"defaultValue": "red",
"description": "Uncontrolled fallback after storage and document accent."
},
{
"prop": "ThemeProvider.onAccentChange",
"type": "(accent: Accent) => void",
"defaultValue": "undefined",
"description": "Receives setAccent requests in either mode; controlled changes are not persisted."
},
{
"prop": "useTheme().theme",
"type": "dark | light",
"defaultValue": "dark",
"description": "Current theme."
},
{
"prop": "useTheme().accent",
"type": "Accent",
"defaultValue": "red",
"description": "Current accent scheme."
},
{
"prop": "useTheme().setAccent",
"type": "(accent: Accent) => void",
"defaultValue": "undefined",
"description": "Persists uncontrolled changes; controlled mode reports through the callback or is a no-op."
},
{
"prop": "useTheme().toggleTheme",
"type": "() => void",
"defaultValue": "undefined",
"description": "Switches and persists the theme."
},
{
"prop": "ThemeToggle",
"type": "component",
"defaultValue": "undefined",
"description": "Ready-made theme switch control."
}
],
"states": [
"dark",
"light",
"red / green / blue / orange / yellow / purple / teal / pink / magenta"
],
"accessibility": [
"ThemeToggle exposes a labelled button.",
"Every accent is browser contrast-tested on dark and light foundations.",
"Respect saved theme and accent setup before rendering content.",
"Never communicate meaning by accent color alone; status colors remain independent."
],
"composition": [
"Wrap the app once with ThemeProvider.",
"Use useTheme for custom controls.",
"Use semantic accent tokens; destructive and feedback colors retain their meanings."
],
"code": "",
"slug": "theme",
"summary": "Application-level dark/light and accent state, persistence, reduced-motion configuration, and a ready-made switch action.",
"sourcePath": "src/components/ThemeProvider.tsx",
"packageExports": [
"ThemeProvider",
"useTheme",
"ThemeToggle",
"Theme",
"Accent",
"accentNames",
"ThemeContextValue",
"ThemeProviderProps"
],
"anatomy": [
{
"name": "Theme provider",
"description": "Context owner and document class/data-attribute synchronizer.",
"required": true
},
{
"name": "Motion configuration",
"description": "Global reduced-motion policy set to user preference.",
"required": true
},
{
"name": "Theme toggle",
"description": "Optional 44px icon action that reads and changes context.",
"required": false,
"semanticElement": "button"
},
{
"name": "Root theme class",
"description": "Document hook that activates dark/light semantic token overrides and native color-scheme.",
"required": true,
"semanticElement": "html.light"
},
{
"name": "Root accent attribute",
"description": "Document hook selecting the active accent scheme.",
"required": true,
"semanticElement": "html[data-accent]"
}
],
"visualSpec": {
"measurements": [
{
"property": "ThemeToggle target",
"value": "44 × 44px"
},
{
"property": "ThemeToggle icon",
"value": "18 × 18px"
},
{
"property": "Appearance transition",
"value": "300ms colors / 500ms hero images"
},
{
"property": "Toggle tap scale",
"value": "0.85×"
},
{
"property": "Toggle hover scale",
"value": "1.1×"
}
],
"rules": [
"Wrap the application once.",
"Use semantic tokens so components switch without per-component theme or accent branches.",
"Initialize the html class and data-accent before paint in the consuming app to avoid an appearance flash."
]
},
"designTokens": [
{
"token": "--color-bg / surface / surface2",
"purpose": "Theme foundations."
},
{
"token": "--color-text / text2 / text3",
"purpose": "Theme typography hierarchy."
},
{
"token": "--color-accent* / --color-action-primary* / --color-focus / --color-selection",
"purpose": "Role-tuned active accent scheme colors."
},
{
"token": "--color-success / warning / info / error*",
"purpose": "Stable feedback semantics that never follow the accent."
},
{
"token": "--motion-base / --motion-slow",
"purpose": "Theme and image transitions."
}
],
"stateDefinitions": [
{
"name": "dark",
"trigger": "Default or saved dark preference.",
"visual": "Neutral-950 background, light text, dark semantic palette; toggle shows sun.",
"behavior": "toggleTheme stores light and adds html.light."
},
{
"name": "light",
"trigger": "Saved or pre-rendered light preference.",
"visual": "Warm-neutral background, dark text, light semantic palette; toggle shows moon.",
"behavior": "toggleTheme stores dark and removes html.light."
},
{
"name": "accent scheme",
"trigger": "Controlled accent prop, or uncontrolled saved accent > existing data-accent > defaultAccent > red.",
"visual": "Accent, primary action, focus, selection, and supporting accent roles adopt the selected family.",
"behavior": "Uncontrolled setAccent persists, updates html[data-accent], and reports through onAccentChange. Controlled accent is fixed; setAccent reports through onAccentChange without persistence, or is a no-op when no callback exists. Destructive and feedback roles remain unchanged."
}
],
"keyboard": [
{
"key": "Enter / Space",
"action": "Activates ThemeToggle."
},
{
"key": "Tab / Shift+Tab",
"action": "Moves focus to or from ThemeToggle."
}
],
"accessibilitySpec": {
"semantics": "Context provider plus native motion button; ThemeToggle has a state-dependent aria-label and title.",
"accessibleName": "ThemeToggle announces the action it will perform, such as Switch to light mode.",
"requirements": [
"Run a pre-hydration appearance script or equivalent to keep theme, accent, and context state aligned at first paint.",
"Do not encode information solely in the active theme or accent.",
"Every accent role must retain its browser-tested contrast contract across all dark/light foundations.",
"MotionConfig and CSS reduced-motion rules must remain enabled."
]
},
"implementation": {
"importStatement": "import { ThemeProvider, ThemeToggle, useTheme } from '@ai-created/ui';",
"clientComponent": true,
"notes": [
"ThemeProvider reads localStorage after mount and falls back to the existing html class or dark.",
"accent is controlled and fixed; defaultAccent is the uncontrolled fallback and red is the default.",
"onAccentChange receives setAccent requests in either mode; controlled changes are never persisted.",
"Uncontrolled precedence is valid localStorage[accent] > existing html[data-accent] > defaultAccent > red.",
"toggleTheme updates context, localStorage, html.light, and temporarily adds theme-transitioning.",
"Uncontrolled setAccent updates context, localStorage[accent], html[data-accent], and calls onAccentChange when provided.",
"The transition class is removed after the 500ms theme-media window, restarted on repeated toggles, and cleaned on unmount.",
"The token stylesheet sets color-scheme for native controls in both modes.",
"useTheme outside a provider receives the safe dark/red default context."
]
},
"guidance": {
"dos": [
"Apply the initial document class before React hydration.",
"Use useTheme only for behavior or media that cannot be expressed through tokens."
],
"donts": [
"Do not hard-code dark-only colors inside components.",
"Do not nest competing ThemeProviders."
]
},
"testing": {
"unit": [
"Resolves saved, existing-class, default themes, and uncontrolled accent precedence.",
"Controlled accent wins over storage/document/default; callback and no-op behavior are covered.",
"toggleTheme updates context, storage, and document class.",
"Uncontrolled setAccent updates context, storage, and html[data-accent]."
],
"interaction": [
"ThemeToggle changes mode by pointer and keyboard and updates its label/icon."
],
"accessibility": [
"Accent choices have an accessible name and do not communicate meaning by color alone; reduced-motion preference is honored."
],
"visual": [
"Capture every foundation and public component across all nine accents and both themes, including transition and no-motion states; browser-test accent text, muted text, borders, actions, focus, selection, and action foregrounds on bg, surface, and surface2."
]
},
"relatedComponents": [
"themed-hero-image",
"motion-helpers",
"button"
],
"controls": {
"theme": {
"type": "select",
"label": "Theme",
"defaultValue": "dark",
"options": [
"dark",
"light"
]
},
"accent": {
"type": "select",
"label": "Accent",
"defaultValue": "red",
"options": [
"red",
"green",
"blue",
"orange",
"yellow",
"purple",
"teal",
"pink",
"magenta"
]
}
},
"construction": {
"asset": {
"kind": "provider",
"figmaName": null,
"localName": "ThemeProvider / useTheme / ThemeToggle",
"canvasApplicability": "ThemeProvider and useTheme have no canvas geometry. Represent dark and light through Figma variable modes; document ThemeToggle separately as the visible consumer."
},
"autoLayout": {
"applicable": false,
"direction": "none",
"gap": "Not applicable",
"padding": "Not applicable",
"alignment": "Not applicable",
"wrap": "Not applicable",
"notes": [
"A context provider and hook do not have a rendered layout box."
]
},
"resizing": {
"applicable": false,
"width": "not-applicable",
"height": "not-applicable",
"minWidth": "Not applicable",
"maxWidth": "Not applicable",
"minHeight": "Not applicable",
"maxHeight": "Not applicable",
"overflow": "not-applicable",
"notes": [
"Provider and hook dimensions are not applicable; child layout remains unchanged."
]
},
"exposedProperties": [
{
"name": "theme",
"label": "Theme mode",
"type": "variant",
"required": false,
"defaultValue": "dark",
"options": [
"dark",
"light"
],
"codeMapping": "ThemeProvider context and the dark or light Figma variable mode"
},
{
"name": "accent",
"label": "Accent scheme",
"type": "variant",
"required": false,
"defaultValue": "red",
"options": [
"red",
"green",
"blue",
"orange",
"yellow",
"purple",
"teal",
"pink",
"magenta"
],
"codeMapping": "ThemeProvider context and active data-accent selector"
},
{
"name": "children",
"label": "Application subtree",
"type": "slot",
"required": true,
"defaultValue": null,
"codeMapping": "ThemeProvider children"
}
],
"nestedAssets": [
{
"name": "Theme context",
"kind": "provider",
"required": true,
"description": "Stores and exposes the active mode and accent scheme.",
"codeMapping": "ThemeProvider and useTheme"
},
{
"name": "Motion configuration",
"kind": "provider",
"required": true,
"description": "Honors the user reduced-motion preference.",
"codeMapping": "MotionConfig inside ThemeProvider"
},
{
"name": "ThemeToggle",
"kind": "subcomponent",
"required": false,
"description": "Ready-made visible mode switch.",
"codeMapping": "ThemeToggle"
}
],
"contentLimits": [
{
"target": "Provider instances",
"limit": "One provider at the application root",
"overflowBehavior": "Remove nested ownership unless an isolated preview explicitly requires it.",
"rationale": "Multiple competing global theme owners cause inconsistent persistence."
}
],
"localization": {
"translatable": [
"ThemeToggle accessible label and title"
],
"rtlBehavior": [
"Theme mode is direction-neutral.",
"Toggle placement follows the consuming layout."
],
"stressCases": [
"Test localized mode names in the toggle.",
"Test first render without stored preference."
]
},
"responsive": {
"strategy": "No provider geometry; all descendants retain their own responsive contracts.",
"breakpoints": [
"Not applicable to provider"
],
"behavior": [
"ThemeToggle preserves its 44px square footprint wherever placed."
]
},
"limitations": {
"figma": [
"There is no Figma component instance for context behavior; use variable modes and a documented visible toggle.",
"Prototype variables do not reproduce localStorage persistence, accent persistence, or pre-hydration theme resolution."
],
"code": [
"Wrap the app once and avoid component-owned global mode changes.",
"Keep destructive and feedback colors independent from the selected accent."
],
"notApplicable": [
"Auto layout, padding, gap, resizing, and overflow do not apply to ThemeProvider or useTheme."
]
},
"governance": {
"status": "stable",
"ownerRole": "Design systems theming foundations owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/components/ThemeProvider.tsx",
"changePolicy": [
"Mode, accent, persistence, root selector, or styles/tokens.css changes require token, rendering, and accessibility review across every scheme and both themes.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
},
{
"id": "cn",
"name": "cn",
"category": "Utilities & motion",
"purpose": "Combines conditional class strings and resolves conflicting Tailwind utilities.",
"useWhen": [
"A component needs conditional classes or consumer className merging"
],
"avoidWhen": [
"A static className needs no composition"
],
"api": [
{
"prop": "...inputs",
"type": "Array",
"defaultValue": "required",
"description": "Class fragments in precedence order."
}
],
"states": [
"not applicable"
],
"accessibility": [
"Class merging must not remove focus, disabled, or semantic state styles."
],
"composition": [
"Pass the consumer className last when it should override defaults."
],
"code": "const classes = cn(\"rounded-md border\", active && \"border-accent\", className);",
"slug": "cn",
"summary": "The class-composition utility that filters conditional fragments and resolves conflicting Tailwind utilities.",
"sourcePath": "src/lib/utils.ts",
"packageExports": [
"cn"
],
"anatomy": [
{
"name": "Input fragments",
"description": "Ordered strings or falsy conditional values.",
"required": true
},
{
"name": "Falsy filter",
"description": "Removes false, null, and undefined inputs.",
"required": true
},
{
"name": "Tailwind merge",
"description": "Resolves utility conflicts by precedence.",
"required": true
},
{
"name": "Class string",
"description": "Serializable final className.",
"required": true
}
],
"visualSpec": {
"measurements": [
{
"property": "Output",
"value": "One whitespace-delimited class string"
}
],
"rules": [
"Put default classes first and the consumer className last when overrides are allowed.",
"Do not use arbitrary class conflicts as a substitute for explicit variants.",
"Focus and semantic-state utilities are part of the component contract."
]
},
"designTokens": [
{
"token": "Consumer-defined semantic tokens",
"purpose": "cn preserves token-backed Tailwind utilities while resolving conflicts."
}
],
"stateDefinitions": [
{
"name": "not applicable",
"trigger": "Called during class composition.",
"visual": "No visual output by itself.",
"behavior": "Returns the Tailwind-merged string."
}
],
"keyboard": [],
"accessibilitySpec": {
"semantics": "No DOM semantics; output affects the consuming element only.",
"accessibleName": "Not applicable.",
"requirements": [
"Do not merge away required focus-visible, disabled, hidden, or contrast styles.",
"The consuming component remains responsible for semantics."
]
},
"implementation": {
"importStatement": "import { cn } from '@ai-created/ui';",
"clientComponent": false,
"notes": [
"Accepts only string, false, null, and undefined fragments.",
"Falsy values are filtered before tailwind-merge runs.",
"Later conflicting utilities take precedence according to tailwind-merge."
]
},
"guidance": {
"dos": [
"Use for conditional variants and intentional consumer overrides.",
"Keep class ordering predictable."
],
"donts": [
"Do not pass untrusted class strings.",
"Do not hide component variant logic in long ad-hoc condition chains."
]
},
"testing": {
"unit": [
"Filters falsy values and preserves non-conflicting order.",
"Resolves representative Tailwind conflicts in favor of later utilities."
],
"interaction": [
"Not applicable."
],
"accessibility": [
"Verify merged output retains focus and disabled utilities."
],
"visual": [
"Not applicable; visual coverage belongs to consumers."
]
},
"relatedComponents": [
"button",
"surface"
],
"controls": {
"base": {
"type": "text",
"label": "Base classes",
"defaultValue": "rounded-md px-4 py-3"
},
"conditional": {
"type": "text",
"label": "Conditional classes",
"defaultValue": "bg-surface2 text-text"
},
"enabled": {
"type": "boolean",
"label": "Include conditional",
"defaultValue": true
}
},
"construction": {
"asset": {
"kind": "utility",
"figmaName": null,
"localName": "cn",
"canvasApplicability": "This class-merging function has no Figma or canvas representation."
},
"autoLayout": {
"applicable": false,
"direction": "none",
"gap": "Not applicable",
"padding": "Not applicable",
"alignment": "Not applicable",
"wrap": "Not applicable",
"notes": [
"A pure string utility emits no element and owns no auto-layout mechanics."
]
},
"resizing": {
"applicable": false,
"width": "not-applicable",
"height": "not-applicable",
"minWidth": "Not applicable",
"maxWidth": "Not applicable",
"minHeight": "Not applicable",
"maxHeight": "Not applicable",
"overflow": "not-applicable",
"notes": [
"A pure string utility has no width, height, constraints, or overflow."
]
},
"exposedProperties": [
{
"name": "inputs",
"label": "Class inputs",
"type": "slot",
"required": true,
"defaultValue": null,
"codeMapping": "Function arguments in precedence order"
},
{
"name": "conditional",
"label": "Include conditional input",
"type": "boolean",
"required": false,
"defaultValue": true,
"codeMapping": "Boolean expression passed as an input"
}
],
"nestedAssets": [
{
"name": "tailwind-merge",
"kind": "helper",
"required": true,
"description": "Resolves conflicting Tailwind utility classes.",
"codeMapping": "Internal twMerge dependency"
}
],
"contentLimits": [
{
"target": "Inputs",
"limit": "Class strings plus false, null, or undefined",
"overflowBehavior": "Split complex style decisions into named variant functions.",
"rationale": "The utility is for class composition, not component architecture."
}
],
"localization": {
"translatable": [],
"rtlBehavior": [
"Not applicable; class merging has no reading direction of its own."
],
"stressCases": [
"Verify logical-direction utilities when building localized components."
]
},
"responsive": {
"strategy": "Not applicable; emitted classes inherit Tailwind responsive behavior.",
"breakpoints": [
"Not applicable to utility"
],
"behavior": [
"Responsive behavior is entirely determined by the input class strings."
]
},
"limitations": {
"figma": [
"No Figma asset should be created for this utility."
],
"code": [
"Passing consumer className last is a policy choice; verify that it cannot remove required state or accessibility styles."
],
"notApplicable": [
"Canvas geometry, auto layout, component properties, instance swaps, and prototype interactions are not applicable."
]
},
"governance": {
"status": "stable",
"ownerRole": "Design systems engineering foundations owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/lib/utils.ts",
"changePolicy": [
"Input types or merge-engine changes require a repository-wide class precedence audit.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
},
{
"id": "motion-helpers",
"name": "Motion helpers",
"category": "Utilities & motion",
"purpose": "Keeps Framer Motion timing, offsets, easing, reveals, and hover behavior consistent.",
"useWhen": [
"Shared entrance, in-view reveal, stagger, or subtle hover behavior is needed"
],
"avoidWhen": [
"Motion does not clarify hierarchy or state"
],
"api": [
{
"prop": "motionDuration",
"type": "readonly timing object",
"defaultValue": "shared values",
"description": "Instant, fast, base, reveal, section, and ambient durations."
},
{
"prop": "motionOffset",
"type": "readonly offset object",
"defaultValue": "shared values",
"description": "Small, medium, large, and hover distances."
},
{
"prop": "motionEase",
"type": "readonly easing object",
"defaultValue": "shared values",
"description": "Standard, in-out, and out easing."
},
{
"prop": "staggerDelay",
"type": "(index, step?, base?) => number",
"defaultValue": "step 0.1, base 0",
"description": "Calculates a list-item delay."
},
{
"prop": "fadeUpMotion",
"type": "(delay?, y?, duration?) => MotionProps",
"defaultValue": "shared reveal values",
"description": "Returns mount animation props."
},
{
"prop": "inViewFadeUpMotion",
"type": "(delay?, y?, duration?) => MotionProps",
"defaultValue": "shared reveal values",
"description": "Returns one-time viewport reveal props."
},
{
"prop": "subtleHoverMotion",
"type": "(distance?) => MotionProps",
"defaultValue": "2px",
"description": "Returns subtle hover lift props."
},
{
"prop": "borderHoverMotion",
"type": "(distance?, borderColor?) => MotionProps",
"defaultValue": "4px, border-strong",
"description": "Returns lift plus border emphasis."
}
],
"states": [
"entry",
"in view",
"hover",
"reduced motion"
],
"accessibility": [
"ThemeProvider configures Framer Motion to honor the user reduced-motion preference.",
"Never rely on motion alone to communicate meaning."
],
"composition": [
"Spread helper results onto a Framer Motion element."
],
"code": "...",
"slug": "motion-helpers",
"summary": "Shared timing, easing, offsets, reveal recipes, and subtle hover behavior for Framer Motion.",
"sourcePath": "src/lib/motion.ts",
"packageExports": [
"motionDuration",
"motionOffset",
"motionEase",
"staggerDelay",
"fadeUpMotion",
"inViewFadeUpMotion",
"subtleHoverMotion",
"borderHoverMotion"
],
"anatomy": [
{
"name": "Duration scale",
"description": "Six named timings from instant to ambient.",
"required": true
},
{
"name": "Offset scale",
"description": "Reveal and hover travel distances.",
"required": true
},
{
"name": "Easing scale",
"description": "Standard cubic bezier and named Framer easings.",
"required": true
},
{
"name": "Reveal helpers",
"description": "Serializable Framer Motion prop objects for mount and in-view entrance.",
"required": true
},
{
"name": "Hover helpers",
"description": "Serializable lift and border-emphasis prop objects.",
"required": true
}
],
"visualSpec": {
"measurements": [
{
"property": "Durations",
"value": "150 / 200 / 300 / 500 / 600 / 1500ms"
},
{
"property": "Reveal offsets",
"value": "16 / 20 / 30px"
},
{
"property": "Hover offsets",
"value": "2 / 4px"
},
{
"property": "Default stagger",
"value": "100ms per item"
}
],
"rules": [
"Use motion to clarify hierarchy or state, not to decorate every element.",
"Prefer shared values over one-off durations and distances.",
"In-view reveals run once by default.",
"Do not rely on motion alone to communicate meaning."
]
},
"designTokens": [
{
"token": "--motion-fast",
"purpose": "CSS equivalent of 200ms interactions."
},
{
"token": "--motion-base",
"purpose": "CSS equivalent of 300ms transitions."
},
{
"token": "--motion-slow",
"purpose": "CSS equivalent of 500ms reveals/cross-fades."
},
{
"token": "--color-border-strong",
"purpose": "Default borderHoverMotion emphasis."
}
],
"stateDefinitions": [
{
"name": "entry",
"trigger": "fadeUpMotion props mount.",
"visual": "Opacity moves 0→1 while y moves to 0.",
"behavior": "Runs immediately with optional delay."
},
{
"name": "in view",
"trigger": "inViewFadeUpMotion enters viewport.",
"visual": "Same fade-up treatment.",
"behavior": "Runs once when observed."
},
{
"name": "hover",
"trigger": "Pointer hover on a motion element.",
"visual": "Element lifts 2px or 4px; border helper also strengthens border.",
"behavior": "Returns over the shared fast duration."
},
{
"name": "reduced motion",
"trigger": "User requests reduced motion under ThemeProvider MotionConfig.",
"visual": "Framer Motion reduces transform motion according to user preference; global CSS collapses animation durations.",
"behavior": "Meaning and interaction remain available without animation."
}
],
"keyboard": [],
"accessibilitySpec": {
"semantics": "Helpers return presentation props only and do not alter DOM semantics.",
"accessibleName": "Not applicable.",
"requirements": [
"Render motion elements with the correct semantic element and focus behavior.",
"Use within ThemeProvider so MotionConfig honors the user preference.",
"Never delay essential content or input availability behind animation.",
"Avoid hover-only information."
]
},
"implementation": {
"importStatement": "import { fadeUpMotion, inViewFadeUpMotion, staggerDelay } from '@ai-created/ui';",
"clientComponent": false,
"notes": [
"Helpers return plain serializable-compatible Framer Motion prop objects.",
"staggerDelay is deterministic and supports custom step/base.",
"borderHoverMotion accepts a CSS color string and defaults to the strong-border token.",
"Consumers provide the motion.* element and semantic tag."
]
},
"guidance": {
"dos": [
"Use subtle consistent motion for hierarchy changes.",
"Test the result with reduced motion enabled."
],
"donts": [
"Do not stagger large lists so late content feels blocked.",
"Do not apply hover lift to controls where movement harms targeting."
]
},
"testing": {
"unit": [
"Constants stay immutable and helpers return exact expected prop shapes.",
"staggerDelay handles zero, custom base, and custom step."
],
"interaction": [
"In-view fires once and hover returns to rest.",
"Reduced-motion configuration suppresses nonessential movement."
],
"accessibility": [
"No content or state is conveyed only through movement."
],
"visual": [
"Record representative entry, stagger, hover, and reduced-motion states."
]
},
"relatedComponents": [
"theme",
"themed-hero-image",
"surface"
],
"controls": {
"delay": {
"type": "number",
"label": "Delay",
"defaultValue": 0,
"min": 0,
"max": 2,
"step": 0.1,
"unit": "s"
},
"offset": {
"type": "number",
"label": "Offset",
"defaultValue": 20,
"min": 0,
"max": 60,
"step": 1,
"unit": "px"
},
"duration": {
"type": "number",
"label": "Duration",
"defaultValue": 0.5,
"min": 0,
"max": 2,
"step": 0.05,
"unit": "s"
}
},
"construction": {
"asset": {
"kind": "helper",
"figmaName": null,
"localName": "Motion helpers",
"canvasApplicability": "Functions and timing constants have no reusable Figma component geometry. Document approved motion tokens and prototype examples instead."
},
"autoLayout": {
"applicable": false,
"direction": "none",
"gap": "Not applicable",
"padding": "Not applicable",
"alignment": "Not applicable",
"wrap": "Not applicable",
"notes": [
"Motion helper functions return Framer Motion props and emit no layout container."
]
},
"resizing": {
"applicable": false,
"width": "not-applicable",
"height": "not-applicable",
"minWidth": "Not applicable",
"maxWidth": "Not applicable",
"minHeight": "Not applicable",
"maxHeight": "Not applicable",
"overflow": "not-applicable",
"notes": [
"Motion helper functions own transforms and timing, not geometry constraints."
]
},
"exposedProperties": [
{
"name": "delay",
"label": "Delay",
"type": "number",
"required": false,
"defaultValue": 0,
"codeMapping": "fadeUpMotion or inViewFadeUpMotion delay argument"
},
{
"name": "offset",
"label": "Vertical offset",
"type": "number",
"required": false,
"defaultValue": 20,
"codeMapping": "y argument or motionOffset token"
},
{
"name": "duration",
"label": "Duration",
"type": "number",
"required": false,
"defaultValue": 0.5,
"codeMapping": "duration argument or motionDuration token"
},
{
"name": "distance",
"label": "Hover distance",
"type": "number",
"required": false,
"defaultValue": 2,
"codeMapping": "subtleHoverMotion or borderHoverMotion distance argument"
}
],
"nestedAssets": [
{
"name": "motionDuration",
"kind": "helper",
"required": true,
"description": "Approved timing constants.",
"codeMapping": "motionDuration"
},
{
"name": "motionOffset",
"kind": "helper",
"required": true,
"description": "Approved translation distances.",
"codeMapping": "motionOffset"
},
{
"name": "motionEase",
"kind": "helper",
"required": true,
"description": "Approved easing curves.",
"codeMapping": "motionEase"
},
{
"name": "Motion element",
"kind": "slot",
"required": true,
"description": "Consumer-owned Framer Motion element receiving helper output.",
"codeMapping": "Spread returned props onto motion.*"
}
],
"contentLimits": [
{
"target": "Concurrent effects",
"limit": "One primary entrance or hover effect per element",
"overflowBehavior": "Remove competing transforms and ambient loops.",
"rationale": "Motion should clarify hierarchy without becoming decoration."
},
{
"target": "Staggered collections",
"limit": "Keep total sequence short enough that the last item is not delayed from use",
"overflowBehavior": "Reduce step or animate groups rather than every row.",
"rationale": "Content must remain promptly available."
}
],
"localization": {
"translatable": [],
"rtlBehavior": [
"Transforms must not encode reading direction unless a product-specific helper explicitly does so."
],
"stressCases": [
"Test reduced motion.",
"Test layout in both directions to ensure transforms do not imply the wrong flow."
]
},
"responsive": {
"strategy": "No intrinsic geometry; the receiving element owns responsive behavior.",
"breakpoints": [
"Not applicable to helper"
],
"behavior": [
"Reduce or remove spatial motion where small screens make displacement distracting.",
"Do not delay interactivity while animation completes."
]
},
"limitations": {
"figma": [
"Figma prototype easing and timing are reference approximations, not the canonical implementation.",
"Do not create a detached component for each animation helper."
],
"code": [
"ThemeProvider is required for the shared reduced-motion policy.",
"Helper output may be overridden by later Framer Motion props."
],
"notApplicable": [
"Auto layout, component resizing, text limits, and instance swapping are not owned by motion helpers."
]
},
"governance": {
"status": "stable",
"ownerRole": "Design systems motion foundations owner",
"lastReviewed": "2026-08-29",
"canonicalSource": "src/lib/motion.ts",
"changePolicy": [
"Token or helper changes require reduced-motion review and regression checks on every consumer category.",
"A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.",
"The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change."
]
}
}
}
],
"guidelines": [
{
"slug": "foundations",
"index": "01",
"title": "Foundations",
"shortTitle": "Foundations",
"summary": "The visual, spatial, typographic, motion, media, and accessible accent-scheme decisions that every AI-Created interface inherits.",
"status": "canonical",
"owner": "Design Systems",
"lastReviewed": "August 2026",
"reviewCycle": "Quarterly and before any token release",
"sourceOfTruth": "styles/tokens.css and tailwind-preset.js",
"outcomes": [
"A product can switch themes and accent schemes without local color overrides.",
"Design decisions map to named semantic tokens before component styling.",
"Layouts remain readable from 320px through the 1400px container maximum."
],
"sections": [
{
"id": "token-architecture",
"title": "Token architecture",
"summary": "Use a three-level naming model so raw values can change without altering product intent.",
"blocks": [
{
"type": "table",
"title": "Decision hierarchy",
"columns": [
"Level",
"Example",
"Who uses it",
"Rule"
],
"rows": [
[
"Reference",
"--ref-red-500",
"System maintainers",
"Stores a raw value. Never use directly in product UI."
],
[
"Semantic",
"--color-action-primary",
"Designers and engineers",
"Names intent and owns light and dark mode behavior."
],
[
"Component",
"Button / Primary / Background",
"Component authors",
"Maps a component decision to a semantic token."
]
]
},
{
"type": "rules",
"title": "Token rules",
"items": [
{
"title": "Name the purpose",
"description": "A token should explain why the value exists, not what its current hex value resembles."
},
{
"title": "Change every scheme together",
"description": "Every accent role is tuned and reviewed across all nine schemes and light/dark mode, including focus and selection; feedback semantics remain stable."
},
{
"title": "Avoid product aliases",
"description": "Do not create a new token for one screen. Promote a value only after a repeated semantic need is demonstrated."
},
{
"title": "Keep compatibility aliases secondary",
"description": "Existing red aliases remain supported public contracts. New work can prefer accent and action names when intent is unambiguous."
}
]
}
]
},
{
"id": "color",
"title": "Color and contrast",
"summary": "Accent schemes, committed actions, destructive actions, neutral surfaces, and semantic feedback each have an explicit role.",
"blocks": [
{
"type": "tokens",
"title": "Core semantic palette",
"description": "Samples resolve live through the current theme.",
"items": [
{
"name": "Background",
"value": "Canvas",
"purpose": "Page background and highest-level negative space.",
"cssVariable": "--color-bg"
},
{
"name": "Surface",
"value": "Primary surface",
"purpose": "Cards, panels, fields, and floating regions.",
"cssVariable": "--color-surface"
},
{
"name": "Surface 2",
"value": "Nested surface",
"purpose": "Controls, inset regions, and subtle grouping.",
"cssVariable": "--color-surface2"
},
{
"name": "Text",
"value": "Primary content",
"purpose": "Headings, labels, and critical information.",
"cssVariable": "--color-text"
},
{
"name": "Accent",
"value": "Identity",
"purpose": "Links, emphasis, and non-destructive branded actions.",
"cssVariable": "--color-accent"
},
{
"name": "Action primary",
"value": "Committed action",
"purpose": "High-emphasis action fill.",
"cssVariable": "--color-action-primary"
},
{
"name": "Action destructive",
"value": "Consequential action",
"purpose": "Destructive action fill, distinct from ordinary commitment.",
"cssVariable": "--color-action-destructive"
},
{
"name": "Control border",
"value": "Interactive boundary",
"purpose": "Contrast-safe boundaries for inputs and outlined controls.",
"cssVariable": "--color-control-border"
},
{
"name": "Success",
"value": "Positive state",
"purpose": "Completed or healthy outcomes only.",
"cssVariable": "--color-success"
},
{
"name": "Warning",
"value": "Attention state",
"purpose": "Recoverable risk or pending attention.",
"cssVariable": "--color-warning"
},
{
"name": "Info",
"value": "Neutral state",
"purpose": "Contextual or process information.",
"cssVariable": "--color-info"
},
{
"name": "Error",
"value": "Failure state",
"purpose": "Invalid input, failed operations, and destructive risk.",
"cssVariable": "--color-error"
}
]
},
{
"type": "checklist",
"title": "Color acceptance",
"groups": [
{
"title": "Required",
"items": [
"Body text meets 4.5:1 contrast.",
"Large text and icons conveying meaning meet 3:1 contrast.",
"Focus indicators meet 3:1 against adjacent colors.",
"Meaning never relies on color alone."
]
},
{
"title": "Avoid",
"items": [
"Raw reference colors in product code.",
"Accent decoration competing with primary actions.",
"Tinted text on tinted surfaces without contrast validation.",
"Theme-specific assets without a paired alternative.",
"Letting accent schemes change destructive or feedback meanings."
]
}
]
}
]
},
{
"id": "type-layout",
"title": "Typography, spacing, and grid",
"summary": "Instrument Serif creates editorial moments. Space Grotesk carries every functional reading task.",
"blocks": [
{
"type": "table",
"title": "Type roles",
"columns": [
"Role",
"Family",
"Typical size",
"Use"
],
"rows": [
[
"Display / Hero",
"Instrument Serif",
"60 to 96px",
"One primary narrative statement per page."
],
[
"Display / Section",
"Instrument Serif",
"40 to 60px",
"Major chapter introductions."
],
[
"Heading",
"Space Grotesk 500",
"20 to 32px",
"Functional page and card hierarchy."
],
[
"Body",
"Space Grotesk 400",
"14 to 20px",
"Instructions, descriptions, and long-form content."
],
[
"Metadata",
"System mono",
"10 to 12px",
"Tokens, statuses, keyboard keys, and code-adjacent labels."
]
]
},
{
"type": "table",
"title": "Responsive layout contract",
"columns": [
"Range",
"Gutter",
"Columns",
"Behavior"
],
"rows": [
[
"320 to 767px",
"6vw",
"4",
"Stack content, preserve source order, use full-width controls when needed."
],
[
"768 to 1023px",
"2vw",
"8",
"Introduce split regions only when each column remains readable."
],
[
"1024 to 1399px",
"2vw",
"12",
"Enable persistent secondary navigation and dense matrices."
],
[
"1400px and above",
"2vw",
"12",
"Cap primary content at 1400px and grow outer whitespace."
]
]
},
{
"type": "rules",
"title": "Composition rules",
"items": [
{
"title": "Use a 4px base unit",
"description": "Tokenized radii and intentional optical adjustments may differ, but layout spacing should resolve to the base unit."
},
{
"title": "Prefer gap over margins",
"description": "Parent layout owns relationships between siblings. Components own only their internal spacing."
},
{
"title": "Keep reading measures controlled",
"description": "Body copy should usually remain between 45 and 75 characters per line."
},
{
"title": "Preserve hierarchy when stacking",
"description": "Responsive changes may alter layout, never the semantic or focus order."
}
]
}
]
},
{
"id": "shape-motion-media",
"title": "Shape, elevation, motion, icons, and media",
"summary": "Secondary visual systems remain restrained so content and interaction state stay primary.",
"blocks": [
{
"type": "table",
"title": "System inventory",
"columns": [
"Area",
"Contract",
"Current support"
],
"rows": [
[
"Radius",
"4px small, 6px default, 10px large, full for pills",
"Canonical tokens"
],
[
"Elevation",
"Border first; shadow only when depth changes interaction meaning",
"Local Tailwind effects, not yet canonical tokens"
],
[
"Motion",
"200ms feedback, 300ms transitions, 500ms entrances",
"Canonical duration tokens and shared helpers"
],
[
"Icons",
"Lucide, 16px inline, 20px controls, 32px empty states",
"Code dependency; no separate icon package"
],
[
"Imagery",
"Theme-paired, art-directed, useful at crop extremes",
"ThemedHeroImage plus product-owned assets"
],
[
"Data visualization",
"Text, shape, and pattern reinforce color",
"Guidance only; no chart primitive yet"
]
]
},
{
"type": "checklist",
"title": "Media and motion acceptance",
"groups": [
{
"title": "Motion",
"items": [
"Animate opacity and transforms when possible.",
"Respect prefers-reduced-motion.",
"Keep focus and reading order stable during transitions.",
"Use motion to explain state or hierarchy, never as idle decoration."
]
},
{
"title": "Media",
"items": [
"Provide useful alt text or mark decorative media as empty alt.",
"Test both theme sources and missing-image fallbacks.",
"Preserve the subject at mobile and wide crops.",
"Include captions or transcripts for time-based media."
]
}
]
}
]
}
],
"sourcePath": "playground/src/components/design-system/principal-spec/registry.ts"
},
{
"slug": "construction",
"index": "02",
"title": "Component construction",
"shortTitle": "Construction",
"summary": "Figma-equivalent component anatomy, sizing, properties, slots, overrides, and design-to-code parity rules.",
"status": "operational",
"owner": "Design Systems and Frontend Platform",
"lastReviewed": "August 2026",
"reviewCycle": "With every component API change",
"sourceOfTruth": "playground component specs and src/components",
"outcomes": [
"A designer can create a supported instance without detaching it.",
"Each design property maps to a public prop, slot, or documented composition.",
"Resize, localization, and exceptional-state behavior is decided before release."
],
"sections": [
{
"id": "asset-model",
"title": "Asset model and naming",
"summary": "One component set represents one public concept. Names encode hierarchy, not visual styling.",
"blocks": [
{
"type": "table",
"title": "Layer naming model",
"columns": [
"Layer",
"Pattern",
"Example",
"Rule"
],
"rows": [
[
"Library asset",
"Component / Name",
"Component / Button",
"Matches the public export name."
],
[
"Variant property",
"Sentence case",
"Variant = Primary",
"Maps to a finite prop union."
],
[
"Boolean property",
"Show + noun",
"Show icon = True",
"Controls optional visibility, not layout hacks."
],
[
"Text property",
"Content role",
"Label = Save",
"Exposes only content intended for instance editing."
],
[
"Nested layer",
"Semantic role",
"Leading icon",
"Names responsibility rather than shape or position."
]
]
},
{
"type": "rules",
"title": "Construction principles",
"items": [
{
"title": "Mirror the public API",
"description": "Variant and boolean properties use the same concepts and defaults as code."
},
{
"title": "Prefer nested components",
"description": "Icons, field messages, and surfaces remain replaceable nested assets where supported."
},
{
"title": "Protect structural layers",
"description": "Consumers may edit content and approved swaps, but should not need to unlock layout layers."
},
{
"title": "Document intentional gaps",
"description": "Utility and provider exports are marked as code-only instead of receiving fictional canvas assets."
}
]
}
]
},
{
"id": "layout-sizing",
"title": "Auto layout and resizing",
"summary": "Each axis has an explicit contract: hug, fill, fixed, or content-controlled.",
"blocks": [
{
"type": "table",
"title": "Sizing decisions",
"columns": [
"Mode",
"Use when",
"Avoid when",
"Code equivalent"
],
"rows": [
[
"Hug",
"Content defines the useful dimension.",
"Peer alignment requires equal widths.",
"inline-flex, w-fit, intrinsic sizing"
],
[
"Fill",
"The parent owns available space.",
"The control should remain content-sized.",
"w-full, flex-1, min-w-0"
],
[
"Fixed",
"The dimension is a tokenized target.",
"Localized text or user content is present.",
"size-* or explicit component token"
],
[
"Content-controlled",
"Media or a consumer slot owns proportion.",
"The component can define a safe default.",
"aspect-ratio, min/max constraints"
]
]
},
{
"type": "checklist",
"title": "Resize stress test",
"groups": [
{
"title": "Canvas",
"items": [
"Test minimum supported width.",
"Test fill-container behavior.",
"Test 200 percent text scaling.",
"Test a three-line translated label.",
"Test optional slots removed and replaced."
]
},
{
"title": "Code",
"items": [
"Verify flex children use min-width: 0 where truncation is intended.",
"Verify hit targets do not shrink below 44 by 44px on touch.",
"Verify overflow is documented as wrap, clip, scroll, or expand.",
"Verify DOM and focus order match the visual layout."
]
}
]
}
]
},
{
"id": "properties-slots",
"title": "Properties, slots, and overrides",
"summary": "Editable surfaces are intentional and finite. They should produce supported code, not arbitrary new component states.",
"blocks": [
{
"type": "rules",
"title": "Property strategy",
"items": [
{
"title": "Variants represent meaningful choice",
"description": "Use a variant only when appearance and behavior form a named, supported option.",
"requirements": [
"No boolean explosion",
"No duplicated state variants",
"No theme property on components"
]
},
{
"title": "State is demonstrated, not configured",
"description": "Hover, focus, pressed, loading, invalid, and disabled are prototype or specimen states unless the API directly owns them."
},
{
"title": "Slots describe composition boundaries",
"description": "A slot declares acceptable content, size, alignment, and fallback behavior."
},
{
"title": "Instance swaps stay type-safe",
"description": "Limit swaps to assets that satisfy the same semantic and dimensional contract."
}
]
},
{
"type": "table",
"title": "Override policy",
"columns": [
"Change",
"Allowed",
"Condition"
],
"rows": [
[
"Text content",
"Yes",
"Within documented content limits and accessible naming rules."
],
[
"Nested icon swap",
"Yes",
"Same icon size and semantic role."
],
[
"Semantic color token",
"By variant only",
"No local fills or raw values."
],
[
"Internal spacing",
"No",
"Request a supported size or composition instead."
],
[
"Layer deletion",
"Boolean property only",
"Do not delete locked structural layers."
],
[
"Detach instance",
"Exception only",
"Requires a documented system gap and follow-up issue."
]
]
}
]
},
{
"id": "parity",
"title": "Design-to-code parity",
"summary": "Parity means equivalent decisions, defaults, states, and behavior. Pixel similarity alone is insufficient.",
"blocks": [
{
"type": "process",
"title": "Parity review",
"steps": [
{
"title": "Inventory",
"owner": "Designer",
"output": "Anatomy, variants, content bounds, resize rules",
"gate": "All supported decisions are represented."
},
{
"title": "Map",
"owner": "Engineer",
"output": "Property-to-prop and slot-to-composition mapping",
"gate": "No design property requires an undocumented override."
},
{
"title": "Stress",
"owner": "Design and QA",
"output": "Theme, locale, zoom, keyboard, state evidence",
"gate": "Both implementations pass the same acceptance cases."
},
{
"title": "Publish",
"owner": "Design Systems",
"output": "Versioned design asset, package release, migration note",
"gate": "Sources publish together or the change remains unreleased."
}
]
},
{
"type": "checklist",
"title": "Definition of parity",
"groups": [
{
"title": "Design",
"items": [
"Names and defaults match code.",
"All public variants and states are demonstrated.",
"Auto layout reproduces responsive intent.",
"Tokens are semantic aliases, not copied values."
]
},
{
"title": "Code",
"items": [
"Public props match documented properties.",
"Native semantics and keyboard behavior are preserved.",
"Visual regression covers both themes.",
"Release notes identify additions, changes, and deprecations."
]
}
]
}
]
}
],
"sourcePath": "playground/src/components/design-system/principal-spec/registry.ts"
},
{
"slug": "patterns",
"index": "03",
"title": "Product patterns",
"shortTitle": "Patterns",
"summary": "Reusable interaction and page-level decisions for common product flows, including their loading, empty, error, and permission states.",
"status": "operational",
"owner": "Product Design",
"lastReviewed": "August 2026",
"reviewCycle": "Quarterly and after major product launches",
"sourceOfTruth": "DESIGN-SYSTEM.md and live pattern specimens",
"outcomes": [
"Common workflows behave consistently across products.",
"Teams design the complete state model before the happy path ships.",
"Patterns compose public primitives without creating hidden component APIs."
],
"sections": [
{
"id": "state-model",
"title": "Complete state model",
"summary": "Every data-backed surface declares what the user sees before, during, and after work.",
"blocks": [
{
"type": "table",
"title": "Required product states",
"columns": [
"State",
"Communicate",
"Primary action",
"Preferred primitive"
],
"rows": [
[
"Initial",
"Purpose and first useful action",
"Start or create",
"EmptyState"
],
[
"Loading",
"Structure and progress without layout shift",
"Usually none",
"Skeleton or inline pending state"
],
[
"Success",
"Result and next step",
"Continue or inspect",
"Notice or refreshed content"
],
[
"Empty result",
"Why no match exists",
"Clear filters or change query",
"EmptyState"
],
[
"Recoverable error",
"What failed and how to retry",
"Retry",
"Notice or inline field message"
],
[
"Diagnostic error",
"Summary plus inspectable details",
"Copy report or retry",
"ErrorReport"
],
[
"Offline",
"Connection dependency and preserved work",
"Retry when online",
"Notice with local state"
],
[
"Permission denied",
"Missing access and request path",
"Request access",
"EmptyState or dedicated page"
]
]
}
]
},
{
"id": "forms-actions",
"title": "Forms and committed actions",
"summary": "Validation stays close to the field while submission status remains clear at the form level.",
"blocks": [
{
"type": "rules",
"title": "Form behavior",
"items": [
{
"title": "Validate at a useful moment",
"description": "Validate on blur or submit. Avoid interrupting the user before a value can be complete."
},
{
"title": "Keep errors persistent",
"description": "Field errors remain visible until the condition is resolved and are associated through description semantics."
},
{
"title": "Preserve input on failure",
"description": "A failed submission must not erase work. Focus the first actionable error when useful."
},
{
"title": "Make submission singular",
"description": "Disable or guard repeated submissions and communicate pending state in the action label."
}
]
},
{
"type": "table",
"title": "Destructive action ladder",
"columns": [
"Risk",
"Pattern",
"Confirmation"
],
"rows": [
[
"Low and reversible",
"Immediate action plus undo",
"No blocking dialog"
],
[
"Material but recoverable",
"ConfirmDialog with consequence",
"Explicit action label"
],
[
"Permanent or high impact",
"ConfirmDialog plus typed or secondary verification",
"Name the object and outcome"
]
]
}
]
},
{
"id": "navigation-discovery",
"title": "Navigation, search, and data discovery",
"summary": "Location, scope, query, filters, and result count remain observable and shareable.",
"blocks": [
{
"type": "checklist",
"title": "Discovery contract",
"groups": [
{
"title": "Navigation",
"items": [
"One page has one primary landmark and heading.",
"Current location is visually and programmatically identifiable.",
"Back behavior returns to a meaningful prior context.",
"Deep links restore the same useful state."
]
},
{
"title": "Search and filters",
"items": [
"Search results appear next to the query, not only as a count.",
"Filters expose active values and a clear-all action.",
"No-results states explain how to recover.",
"Query and filters use URL state when sharing matters."
]
},
{
"title": "Pagination and tables",
"items": [
"Announce result range and total.",
"Preserve sort and selection across pagination deliberately.",
"Keep row actions keyboard reachable.",
"Offer a narrow-screen alternative to horizontal data loss."
]
}
]
}
]
},
{
"id": "page-archetypes",
"title": "Page archetypes",
"summary": "Stable page skeletons reduce navigation and density decisions while leaving room for product content.",
"blocks": [
{
"type": "table",
"title": "Archetype inventory",
"columns": [
"Archetype",
"Required regions",
"Responsive priority"
],
"rows": [
[
"Directory",
"Title, search/filter, result summary, list, empty/error states",
"Keep search and first results above the fold."
],
[
"Detail",
"Breadcrumb/back, identity, status, primary actions, grouped details",
"Keep identity before actions and secondary metadata."
],
[
"Editor",
"Title/status, workspace, controls, validation, save state",
"Preserve the work area and collapse secondary controls."
],
[
"Settings",
"Local navigation, grouped fields, save feedback",
"Stack navigation before fields without losing location."
],
[
"Dashboard",
"Time/scope controls, summary, trends, exceptions",
"Prioritize exceptions and readable comparisons."
],
[
"Onboarding",
"Progress, one decision, help, safe exit",
"One column and one primary action."
]
]
}
]
}
],
"sourcePath": "playground/src/components/design-system/principal-spec/registry.ts"
},
{
"slug": "content",
"index": "04",
"title": "Content design",
"shortTitle": "Content",
"summary": "Voice, interface language, formatting, localization, and accessible naming rules for product content.",
"status": "operational",
"owner": "Product Design and Content",
"lastReviewed": "August 2026",
"reviewCycle": "Twice yearly and with locale expansion",
"sourceOfTruth": "DESIGN-SYSTEM.md content guidelines",
"outcomes": [
"People understand the next action without interpreting system jargon.",
"Errors explain the problem, consequence, and recovery.",
"Layouts survive translation, bidirectional text, and user-generated content."
],
"sections": [
{
"id": "voice",
"title": "Voice and tone",
"summary": "The voice is direct, calm, specific, and human. Tone adjusts to consequence without changing personality.",
"blocks": [
{
"type": "table",
"title": "Voice dimensions",
"columns": [
"Prefer",
"Avoid",
"Example"
],
"rows": [
[
"Specific",
"Vague",
"“Export failed because the file is read-only.”"
],
[
"Direct",
"Ceremonial",
"“Save changes” instead of “Proceed with saving.”"
],
[
"Calm",
"Alarmist",
"“Connection lost. Your draft is saved locally.”"
],
[
"Human",
"Cute or robotic",
"“We could not verify that address.”"
]
]
},
{
"type": "rules",
"title": "Tone by moment",
"items": [
{
"title": "Routine",
"description": "Be compact. Labels and actions should feel almost invisible."
},
{
"title": "Learning",
"description": "Explain the concept and next step without front-loading every exception."
},
{
"title": "Blocked",
"description": "State what happened, whether work is safe, and the most useful recovery."
},
{
"title": "High risk",
"description": "Slow the interaction down. Name the affected object, consequence, and permanence."
}
]
}
]
},
{
"id": "interface-copy",
"title": "Interface copy",
"summary": "Labels describe objects. Actions begin with verbs. Supporting text earns its space.",
"blocks": [
{
"type": "table",
"title": "Copy patterns",
"columns": [
"Element",
"Pattern",
"Example"
],
"rows": [
[
"Button",
"Verb + object when context is not obvious",
"Create project"
],
[
"Field label",
"Stable noun phrase",
"Billing address"
],
[
"Helper text",
"Format, consequence, or reason",
"Used only for account recovery."
],
[
"Validation",
"Problem + correction",
"Enter an email address in name@example.com format."
],
[
"Dialog title",
"Decision or consequence",
"Delete “Quarterly plan”?"
],
[
"Empty state",
"Situation + value + next action",
"No saved views yet. Save this filter to reuse it."
],
[
"Success",
"Completed result",
"Project created"
]
]
},
{
"type": "checklist",
"title": "Copy acceptance",
"groups": [
{
"title": "Every string",
"items": [
"Uses sentence case.",
"Avoids unnecessary punctuation.",
"Does not repeat adjacent headings or labels.",
"Makes sense when read by a screen reader out of visual context."
]
},
{
"title": "Errors",
"items": [
"Names the failed object or action.",
"Avoids blame.",
"Preserves useful technical detail behind disclosure.",
"Offers a recovery when one exists."
]
}
]
}
]
},
{
"id": "formatting",
"title": "Numbers, dates, names, and truncation",
"summary": "Locale-aware formatting is part of the content contract, not post-production cleanup.",
"blocks": [
{
"type": "table",
"title": "Formatting rules",
"columns": [
"Content",
"Display rule",
"Implementation"
],
"rows": [
[
"Dates",
"Use unambiguous localized forms. Include year when context can cross years.",
"Intl.DateTimeFormat"
],
[
"Times",
"Use the user locale and show the time zone when participants differ.",
"Intl.DateTimeFormat with timeZoneName"
],
[
"Numbers",
"Respect grouping and decimal conventions. Keep raw precision only where meaningful.",
"Intl.NumberFormat"
],
[
"Currency",
"Always bind amount to ISO currency. Never infer from symbol alone.",
"Intl.NumberFormat with currency"
],
[
"Names",
"Store and display as entered. Do not require first/last assumptions.",
"One full-name field unless domain needs parts"
],
[
"File size",
"Use consistent decimal or binary units within a product.",
"Shared formatter"
],
[
"Truncation",
"Preserve distinguishing start and end where useful. Reveal the full value.",
"CSS ellipsis plus accessible full text"
]
]
}
]
},
{
"id": "localization",
"title": "Localization and bidirectionality",
"summary": "Components expand, mirror, and reflow without asking translators to fit English-shaped boxes.",
"blocks": [
{
"type": "checklist",
"title": "Localization stress cases",
"groups": [
{
"title": "Translation",
"items": [
"Test 30 to 50 percent text expansion.",
"Do not concatenate sentence fragments.",
"Keep variables contextually named for translators.",
"Use plural rules rather than count-based string branches."
]
},
{
"title": "RTL",
"items": [
"Use logical start and end properties.",
"Mirror directional icons, not universal symbols.",
"Keep numbers, code, and media direction intentional.",
"Verify focus and reading order independently of visual mirroring."
]
},
{
"title": "User content",
"items": [
"Support mixed scripts and bidirectional isolation.",
"Define wrapping for long unbroken strings.",
"Do not communicate status through capitalization.",
"Keep accessible names in the user language."
]
}
]
}
]
}
],
"sourcePath": "playground/src/components/design-system/principal-spec/registry.ts"
},
{
"slug": "accessibility",
"index": "05",
"title": "Accessibility standards",
"shortTitle": "Accessibility",
"summary": "The release contract for inclusive semantics, input, perception, reflow, motion, and assistive technology behavior.",
"status": "canonical",
"owner": "Design Systems and Engineering",
"lastReviewed": "August 2026",
"reviewCycle": "Every release and quarterly manual audit",
"sourceOfTruth": "WCAG 2.2 AA target and component accessibility specs",
"outcomes": [
"Core workflows operate with keyboard and screen reader alone.",
"Content remains usable at 200 percent zoom and 320 CSS pixels.",
"Component releases include automated and manual accessibility evidence."
],
"sections": [
{
"id": "standard",
"title": "Conformance target",
"summary": "WCAG 2.2 Level AA is the minimum. Native semantics and platform conventions are the starting point.",
"blocks": [
{
"type": "table",
"title": "Acceptance matrix",
"columns": [
"Area",
"Minimum",
"Evidence"
],
"rows": [
[
"Contrast",
"4.5:1 text, 3:1 large text and meaningful UI graphics",
"Theme-paired contrast audit"
],
[
"Keyboard",
"All actions reachable, operable, and escapable",
"Interaction tests plus manual pass"
],
[
"Focus",
"Visible, ordered, not obscured, restored after overlays",
"Both themes at desktop and mobile viewport"
],
[
"Touch",
"44 by 44 CSS pixel target where practical",
"Rendered target inspection"
],
[
"Zoom and reflow",
"200 percent zoom and 320 CSS pixel width without lost content",
"Manual browser matrix"
],
[
"Motion",
"Reduced-motion alternative and no unsafe flashing",
"Media query and behavior review"
],
[
"Names and roles",
"Programmatic name, role, value, state",
"Accessibility tree and screen reader"
]
]
}
]
},
{
"id": "interaction",
"title": "Keyboard, focus, and announcements",
"summary": "Keyboard behavior follows the native element or established ARIA pattern, never a visual imitation.",
"blocks": [
{
"type": "rules",
"title": "Interaction requirements",
"items": [
{
"title": "Use native controls first",
"description": "Buttons, links, inputs, selects, and dialogs provide behavior that custom roles must otherwise reproduce."
},
{
"title": "Do not trap focus outside a modal",
"description": "Only active modal dialogs contain focus. Escape closes when cancellation is supported."
},
{
"title": "Return focus intentionally",
"description": "Closing transient UI restores focus to the trigger or the next logical workflow target."
},
{
"title": "Announce outcomes, not activity noise",
"description": "Use live regions for asynchronous results that are not otherwise focused. Avoid repeated progress chatter."
}
]
},
{
"type": "table",
"title": "Common keyboard contracts",
"columns": [
"Pattern",
"Keys"
],
"rows": [
[
"Button and toggle",
"Enter and Space activate"
],
[
"Tabs",
"Arrow keys move; Home and End jump; focus and selection policy is documented"
],
[
"Menu",
"Arrow keys move; Enter selects; Escape closes and restores focus"
],
[
"Dialog",
"Tab cycles inside; Escape cancels when allowed"
],
[
"Slider",
"Arrow keys step; Page keys make larger changes; Home and End set bounds"
],
[
"Radio group",
"Arrow keys move and select within the group"
]
]
}
]
},
{
"id": "perception-reflow",
"title": "Perception, reflow, and user preferences",
"summary": "Information survives theme, forced colors, text spacing, zoom, and reduced motion.",
"blocks": [
{
"type": "checklist",
"title": "Resilience checks",
"groups": [
{
"title": "Visual",
"items": [
"Light and dark themes retain hierarchy.",
"Forced-colors mode preserves controls and focus.",
"Status includes text or shape in addition to color.",
"Browser text-spacing overrides do not clip content."
]
},
{
"title": "Responsive",
"items": [
"No two-dimensional scrolling for ordinary content at 320 CSS pixels.",
"Sticky regions do not obscure focus.",
"Landscape mobile retains primary actions.",
"Tables provide a deliberate narrow-screen strategy."
]
},
{
"title": "Preferences",
"items": [
"Reduced motion removes nonessential movement.",
"Autoplay is absent or user-controlled.",
"Animation does not block interaction.",
"Theme choice persists without flash."
]
}
]
}
]
},
{
"id": "testing",
"title": "Accessibility test responsibilities",
"summary": "Automation catches regressions. Manual evaluation confirms that the workflow is actually understandable.",
"blocks": [
{
"type": "process",
"title": "Release evidence",
"steps": [
{
"title": "Author",
"owner": "Component author",
"output": "Semantic markup, keyboard tests, labels, state announcements",
"gate": "No known serious automated violations."
},
{
"title": "Review",
"owner": "Design Systems",
"output": "Focus, contrast, zoom, reflow, reduced-motion evidence",
"gate": "Both themes and exceptional states pass."
},
{
"title": "Assistive technology",
"owner": "QA or trained reviewer",
"output": "VoiceOver/Safari plus NVDA/Firefox or equivalent workflow notes",
"gate": "Name, role, state, reading order, and recovery are usable."
},
{
"title": "Monitor",
"owner": "Product team",
"output": "Reported issue triage and regression coverage",
"gate": "Critical issues block release; fixes add lasting tests."
}
]
}
]
}
],
"sourcePath": "playground/src/components/design-system/principal-spec/registry.ts"
},
{
"slug": "governance",
"index": "06",
"title": "Governance and contribution",
"shortTitle": "Governance",
"summary": "Ownership, maturity, contribution, release, adoption, exception, and deprecation rules for keeping the system trustworthy.",
"status": "canonical",
"owner": "Design Systems",
"lastReviewed": "August 2026",
"reviewCycle": "Monthly operating review",
"sourceOfTruth": "Repository, package releases, and this portal",
"outcomes": [
"Teams know what is safe to adopt and who decides changes.",
"Design and code publish as one reviewed release.",
"Every consumer release moves through a visible, recoverable adoption lifecycle.",
"Exceptions and deprecations include an owner and an exit path."
],
"sections": [
{
"id": "maturity",
"title": "Maturity and ownership",
"summary": "Every shared asset has a status, accountable owner, review date, and canonical implementation.",
"blocks": [
{
"type": "table",
"title": "Maturity model",
"columns": [
"Status",
"Use",
"Promise"
],
"rows": [
[
"Draft",
"Evaluation only",
"Shape and API may change without migration."
],
[
"Beta",
"Opt-in product use",
"Known gaps are documented; breaking changes include direct outreach."
],
[
"Stable",
"Default for production",
"Semantic versioning, migration guidance, and regression coverage."
],
[
"Deprecated",
"Existing use while migrating",
"Replacement, deadline, and removal version are published."
],
[
"Retired",
"Do not use",
"Removed from active libraries and retained only in history."
]
]
},
{
"type": "table",
"title": "Decision rights",
"columns": [
"Role",
"Accountability"
],
"rows": [
[
"Design Systems",
"System coherence, asset model, tokens, docs, final acceptance"
],
[
"Frontend Platform",
"Public API, semantics, performance, package quality"
],
[
"Product designer",
"Use case evidence, workflow fit, content and responsive validation"
],
[
"Product engineer",
"Integration evidence, edge cases, adoption and migration feedback"
],
[
"Accessibility reviewer",
"Manual behavior and conformance risk"
]
]
}
]
},
{
"id": "contribution",
"title": "Contribution workflow",
"summary": "New system surface area begins with repeated product need, not a polished component proposal.",
"blocks": [
{
"type": "process",
"title": "From need to release",
"steps": [
{
"title": "Frame",
"owner": "Contributor",
"output": "Problem, affected workflows, evidence from at least two contexts",
"gate": "A shared need exists and composition cannot solve it cleanly."
},
{
"title": "Explore",
"owner": "Design and engineering",
"output": "API, anatomy, states, tokens, accessibility, content and responsive model",
"gate": "The smallest coherent contract is selected."
},
{
"title": "Build",
"owner": "Contributor",
"output": "Code, design asset, docs, tests, examples and migration notes",
"gate": "Parity and quality checklist passes."
},
{
"title": "Review",
"owner": "System owners",
"output": "Design, API, accessibility and visual approval",
"gate": "No unresolved release blocker remains."
},
{
"title": "Adopt",
"owner": "Product team",
"output": "Pilot evidence and follow-up issues",
"gate": "Beta graduates after real workflow validation."
}
]
},
{
"type": "checklist",
"title": "Proposal evidence",
"groups": [
{
"title": "Problem",
"items": [
"Two or more concrete product contexts.",
"Why existing primitives and patterns are insufficient.",
"User and accessibility consequences.",
"Expected adoption and maintenance owner."
]
},
{
"title": "Solution",
"items": [
"Public API and design properties.",
"Complete state, content, responsive, locale, and theme model.",
"Token impact and visual rationale.",
"Testing, rollout, and migration plan."
]
}
]
}
]
},
{
"id": "change-management",
"title": "Release and change management",
"summary": "Documentation, package behavior, design assets, and migration guidance move together.",
"blocks": [
{
"type": "table",
"title": "Change classes",
"columns": [
"Class",
"Examples",
"Requirement"
],
"rows": [
[
"Patch",
"Bug fix, docs clarification, accessibility correction without API impact",
"Regression test and changelog entry"
],
[
"Minor",
"New component, prop, token, recipe, or compatible visual capability",
"Docs, examples, design asset, adoption note"
],
[
"Major",
"Removed or renamed API, changed default, token meaning change",
"Deprecation window, codemod or migration, owner outreach"
],
[
"Emergency",
"Security or critical accessibility fix",
"Expedited review plus follow-up documentation and audit"
]
]
},
{
"type": "rules",
"title": "Deprecation contract",
"items": [
{
"title": "Name the replacement",
"description": "A deprecation without a supported next step is not actionable."
},
{
"title": "Provide a deadline",
"description": "Publish the earliest removal version and a review date."
},
{
"title": "Measure remaining use",
"description": "Track package references or product inventory before removal."
},
{
"title": "Keep the old path stable",
"description": "Do not silently change deprecated behavior during the migration window."
}
]
}
]
},
{
"id": "consumer-adoption",
"title": "Consumer adoption lifecycle",
"summary": "Consumers opt into update discovery, validate releases in their own environment, approve them manually, and deploy on their own schedule.",
"blocks": [
{
"type": "process",
"title": "Release to production",
"steps": [
{
"title": "Publish",
"owner": "Design Systems",
"output": "Immutable vX.Y.Z tag, GitHub Release, and reviewed notes",
"gate": "Release workflow passes without moving an existing tag."
},
{
"title": "Propose",
"owner": "Consumer updater",
"output": "An optional package.json and package-lock.json pull request",
"gate": "Both files resolve the same immutable release tag."
},
{
"title": "Validate",
"owner": "Consumer CI",
"output": "Consumer-owned typecheck, lint, tests, policy checks, accessibility checks, and production build",
"gate": "Applicable compatibility checks pass; a provider preview does not substitute for them."
},
{
"title": "Approve",
"owner": "Product owner",
"output": "Release-note and product-impact review",
"gate": "A human merges; automerge stays disabled."
},
{
"title": "Deploy and verify",
"owner": "Consumer owner",
"output": "Normal deployment plus an affected-workflow smoke test",
"gate": "The deployed consumer behaves as reviewed."
},
{
"title": "Monitor",
"owner": "Consumer owner",
"output": "Optional scheduled freshness signal",
"gate": "Monitoring reports staleness without changing the application."
}
]
},
{
"type": "table",
"title": "Choose an adoption path",
"columns": [
"Path",
"Consumer choice",
"Expected result"
],
"rows": [
[
"Renovate",
"Add the focused @ai-created/ui package rule to the consumer repository.",
"Eligible immutable tags produce reviewable pull requests."
],
[
"Scheduled Renovate",
"Add a consumer-chosen schedule to that package rule.",
"Pull requests open during the preferred maintenance window."
],
[
"Manual",
"Update the tagged dependency and regenerate the lockfile together.",
"The same review and compatibility contract applies without a bot."
],
[
"No update",
"Keep the currently installed immutable tag.",
"The existing application remains unchanged."
]
]
},
{
"type": "rules",
"title": "Operational boundaries",
"items": [
{
"title": "No registration required",
"description": "The design-system repository does not need to know which applications consume it. Teams may maintain their own inventory when useful."
},
{
"title": "Compatibility is consumer-owned",
"description": "Each application defines the commands and environments that prove the release works with its stack."
},
{
"title": "Provider checks are separate",
"description": "Deployment previews help review the product but do not replace consumer-owned compatibility checks."
},
{
"title": "Completion includes production",
"description": "A green pull request is not the endpoint. Merge manually, confirm deployment, and verify the affected product workflow."
},
{
"title": "Monitoring reports rather than mutates",
"description": "The optional currency check exposes a stale tag. It does not open, merge, deploy, or verify an update."
},
{
"title": "Recover by fixing forward",
"description": "When compatibility or production verification fails, repair the consumer or publish a new patch. Never move a published tag or weaken a required check."
}
]
}
]
},
{
"id": "health",
"title": "System health and exceptions",
"summary": "A mature library measures use, quality, and drift rather than equating inventory size with success.",
"blocks": [
{
"type": "table",
"title": "Health signals",
"columns": [
"Signal",
"Question"
],
"rows": [
[
"Adoption",
"What share of eligible product surfaces uses the supported primitive or pattern?"
],
[
"Coverage",
"Which recurring product needs still require local implementations?"
],
[
"Quality",
"What accessibility, visual, reliability, and performance regressions recur?"
],
[
"Parity",
"Which design or code assets expose unmatched decisions?"
],
[
"Velocity",
"How long do proposals, reviews, migrations, and critical fixes take?"
],
[
"Trust",
"Can product teams predict behavior, ownership, and upgrade cost?"
]
]
},
{
"type": "rules",
"title": "Exception policy",
"items": [
{
"title": "Record the need",
"description": "State the unmet requirement, affected surface, and why composition fails."
},
{
"title": "Limit the blast radius",
"description": "Keep the exception product-local and avoid naming it like a shared primitive."
},
{
"title": "Assign an owner and review date",
"description": "Every exception expires, graduates, or is explicitly renewed."
},
{
"title": "Feed the system",
"description": "Repeated exceptions become contribution evidence, not permanent forks."
}
]
}
]
}
],
"sourcePath": "playground/src/components/design-system/principal-spec/registry.ts"
},
{
"slug": "assets",
"index": "07",
"title": "Assets and distribution",
"shortTitle": "Assets",
"summary": "Reusable tokens, package exports, presets, icon policy, media requirements, and the source-of-truth map for every consumer.",
"status": "evolving",
"owner": "Design Systems and Frontend Platform",
"lastReviewed": "August 2026",
"reviewCycle": "Every package and token release",
"sourceOfTruth": "Repository package exports and generated token artifact",
"outcomes": [
"Consumers can install or download the system without copying values by hand.",
"Every asset type names its canonical source and update path.",
"Generated exports fail validation when they drift from source CSS."
],
"sections": [
{
"id": "downloads",
"title": "Reusable downloads",
"summary": "The downloadable token artifact is generated from canonical CSS. Code consumers use package exports directly.",
"blocks": [
{
"type": "resources",
"title": "Asset directory",
"items": [
{
"title": "Design tokens JSON",
"description": "Generated DTCG-shaped token data with reference, semantic, layout, radius, motion, and light/dark mode values.",
"href": "/design-system/tokens.json",
"action": "Download JSON"
},
{
"title": "Design-system manifest",
"description": "Versioned machine-readable contract for every public export, component, guideline, source, token dependency, and blocking validation command.",
"href": "/design-system/manifest.json",
"action": "Download JSON"
},
{
"title": "AI agent quick context",
"description": "Concise operating rules and links for tools that discover llms.txt.",
"href": "/llms.txt",
"action": "Open text"
},
{
"title": "AI agent full context",
"description": "Complete readable component, accessibility, implementation, guideline, template, and validation reference.",
"href": "/llms-full.txt",
"action": "Open text"
},
{
"title": "Token CSS",
"description": "Canonical CSS custom properties for product runtimes.",
"href": "https://github.com/TheMarco/ai-created-ui/blob/main/styles/tokens.css",
"action": "View source",
"external": true
},
{
"title": "Tailwind preset",
"description": "Theme mappings, typography families, radii, semantic colors, and motion utilities.",
"href": "https://github.com/TheMarco/ai-created-ui/blob/main/tailwind-preset.js",
"action": "View source",
"external": true
},
{
"title": "Approved page templates",
"description": "Six complete production archetypes with loading, empty, error, permission, and completion states.",
"href": "https://github.com/TheMarco/ai-created-ui/tree/main/templates/agent",
"action": "View source",
"external": true
},
{
"title": "Agent integration guide",
"description": "Query commands, consumer setup, exception policy, CI gates, and MCP adapter guidance.",
"href": "https://github.com/TheMarco/ai-created-ui/blob/main/docs/agent-integration.md",
"action": "Read guide",
"external": true
},
{
"title": "Component package",
"description": "Public React components, utilities, providers, and motion helpers.",
"href": "https://github.com/TheMarco/ai-created-ui",
"action": "Open repository",
"external": true
}
]
},
{
"type": "code",
"title": "Consumer setup",
"description": "Import tokens once, extend the preset, then import public components from the package root.",
"language": "tsx",
"code": "// app/globals.css\n@import '@ai-created/ui/styles/tokens.css';\n\n// tailwind.config.js\nmodule.exports = {\n presets: [require('@ai-created/ui/tailwind-preset')],\n content: ['./src/**/*.{ts,tsx}'],\n};\n\n// product UI\nimport { Button, Surface } from '@ai-created/ui';"
}
]
},
{
"id": "agent-contract",
"title": "AI agent contract",
"summary": "Agents use the same versioned inputs and blocking gates as human contributors, without inferring undocumented design decisions.",
"blocks": [
{
"type": "rules",
"title": "Agent operating model",
"items": [
{
"title": "Query canonical context",
"description": "Read the manifest or query CLI before implementation. Never reconstruct props, variants, or tokens from model memory."
},
{
"title": "Start from an approved archetype",
"description": "Use the directory, detail, form, settings, dashboard, or onboarding template when its product shape matches."
},
{
"title": "Reject silent drift",
"description": "Raw colors, reference tokens, internal imports, arbitrary system values, and local primitive copies fail the policy gate."
},
{
"title": "Make exceptions accountable",
"description": "A necessary departure names one rule, narrow files, a concrete reason, an owner, and a future review date."
}
]
},
{
"type": "code",
"title": "Agent query and validation",
"description": "Commands return JSON and validate the same contract that ships with the selected package version.",
"language": "bash",
"code": "npm run agent:query -- component button\nnpm run agent:query -- guideline accessibility\nnpm run agent:query -- template dashboard\nnpm run agent:check"
},
{
"type": "resources",
"title": "Agent entry points",
"description": "Start at the overview when introducing the model to a team. Stay in this chapter for the canonical rules.",
"items": [
{
"title": "Agents overview",
"description": "Product-level explanation of how agents query the contract, what validation rejects, and how exceptions reach human review.",
"href": "/agents",
"action": "Open page"
},
{
"title": "AI agent integration guide",
"description": "Consumer setup, required gates, repository enforcement, and adapter guidance.",
"href": "https://github.com/TheMarco/ai-created-ui/blob/main/docs/agent-integration.md",
"action": "Read guide",
"external": true
}
]
}
]
},
{
"id": "source-map",
"title": "Source-of-truth map",
"summary": "Each asset has one canonical authoring location and an explicit distribution path.",
"blocks": [
{
"type": "table",
"title": "Asset ownership",
"columns": [
"Asset",
"Canonical source",
"Distribution",
"Change gate"
],
"rows": [
[
"Reference and semantic tokens",
"styles/tokens.css",
"CSS package export and generated JSON",
"Theme and contrast review"
],
[
"Tailwind mappings",
"tailwind-preset.js",
"Preset package export",
"Matches canonical CSS names"
],
[
"React components",
"src/components",
"Package root exports",
"API, a11y, unit, interaction and visual review"
],
[
"Component specifications",
"playground/specs",
"This portal",
"Registry completeness and parity tests"
],
[
"Icons",
"Lucide dependency",
"lucide-react",
"Use standard glyph before custom asset"
],
[
"Product imagery",
"Owning product repository",
"Product deployment",
"Theme, crop, rights and accessibility review"
],
[
"Visual baselines",
"e2e/__screenshots__",
"Repository test artifact",
"Intentional reviewed update"
],
[
"Agent manifest and context",
"Runtime, tokens, registries, templates, and AGENTS.md",
"Package files and portal downloads",
"Generated parity and freshness checks"
]
]
}
]
},
{
"id": "library-model",
"title": "Design library model",
"summary": "A future design-tool library should mirror this portal without becoming a competing source of truth.",
"blocks": [
{
"type": "table",
"title": "Recommended library pages",
"columns": [
"Page",
"Contents"
],
"rows": [
[
"00 Cover and release",
"Version, status, owner, release notes, migration alerts"
],
[
"01 Foundations",
"Variables, text styles, layout, radius, motion, icon and media rules"
],
[
"02 Components",
"Published component sets matching public exports"
],
[
"03 Patterns",
"Approved compositions and complete state flows"
],
[
"04 Accessibility",
"Annotations, focus order, keyboard and announcement notes"
],
[
"05 QA",
"Theme, locale, resize, density and exceptional-state comparison frames"
],
[
"99 Deprecated",
"Migration-only assets with removal version"
]
]
},
{
"type": "rules",
"title": "Publishing policy",
"items": [
{
"title": "Version the release",
"description": "Publish design assets with the corresponding package version and changelog."
},
{
"title": "Expose semantic variables",
"description": "Consumers select intent. Reference values remain hidden from product authoring."
},
{
"title": "Keep code-only exports honest",
"description": "Providers and utilities receive documentation, not artificial canvas components."
},
{
"title": "Audit detached instances",
"description": "Detachment signals either missing capability or unsupported product drift."
}
]
}
]
},
{
"id": "asset-quality",
"title": "Asset quality gates",
"summary": "Reusable assets are complete only when their licensing, modes, states, naming, and fallback behavior are documented.",
"blocks": [
{
"type": "checklist",
"title": "Release checklist by asset type",
"groups": [
{
"title": "Tokens",
"items": [
"Generated artifact matches CSS.",
"Aliases resolve without cycles.",
"Light and dark modes are complete.",
"Names and types remain stable or include migration."
]
},
{
"title": "Icons",
"items": [
"Optical size matches 16, 20, or 32px role.",
"Accessible name comes from the control or nearby text.",
"Directionality is documented.",
"Custom icons include source and license."
]
},
{
"title": "Media",
"items": [
"Usage rights and source are recorded.",
"Light/dark variants and crops are paired.",
"Fallback and alt behavior is defined.",
"Files meet product performance budgets."
]
}
]
}
]
}
],
"sourcePath": "playground/src/components/design-system/principal-spec/registry.ts"
}
],
"validation": {
"policy": "Every command is blocking. A change is publishable only when all commands pass.",
"commands": [
{
"id": "typecheck",
"command": "npm run typecheck",
"purpose": "Validate package and portal TypeScript.",
"blocking": true
},
{
"id": "lint",
"command": "npm run lint",
"purpose": "Validate source, scripts, tests, and portal conventions.",
"blocking": true
},
{
"id": "test",
"command": "npm run test",
"purpose": "Run component and contract tests.",
"blocking": true
},
{
"id": "tokens",
"command": "npm run tokens:check",
"purpose": "Reject stale generated design tokens.",
"blocking": true
},
{
"id": "manifest",
"command": "node scripts/export-design-system-manifest.mjs --check",
"purpose": "Reject a stale or incomplete agent manifest.",
"blocking": true
},
{
"id": "tailwind",
"command": "npm run tailwind:check",
"purpose": "Reject framework mappings that drift from canonical tokens.",
"blocking": true
},
{
"id": "api",
"command": "npm run api:check",
"purpose": "Reject documented props, controls, or imports that drift from the public TypeScript API.",
"blocking": true
},
{
"id": "policy",
"command": "npm run policy:check",
"purpose": "Reject prohibited styling, imports, tokens, and primitive copies.",
"blocking": true
},
{
"id": "templates",
"command": "npm run templates:check",
"purpose": "Compile and verify every approved page template and public export fixture.",
"blocking": true
},
{
"id": "documentation",
"command": "npm run docs:check",
"purpose": "Reject stale public counts, routes, workflows, or propagation guidance.",
"blocking": true
},
{
"id": "agent-context",
"command": "npm run agent-context:check",
"purpose": "Reject stale concise or full agent context artifacts.",
"blocking": true
},
{
"id": "agent",
"command": "npm run agent:check",
"purpose": "Run the complete machine-readable anti-drift contract.",
"blocking": true
},
{
"id": "portal",
"command": "npm run build:playground",
"purpose": "Build the specification portal.",
"blocking": true
},
{
"id": "package",
"command": "npm run package:check",
"purpose": "Verify the distributable package contract.",
"blocking": true
},
{
"id": "full",
"command": "npm run validate",
"purpose": "Run the repository validation gate.",
"blocking": true
}
]
}
}