twntyx-css 1.0.0 → 1.0.2

package/README.md

@@ -1,4 +1,4 @@
-![twntyX CSS Framework](/images/logos/stryda-logo-dark-png.png)
+![twntyX CSS Framework](https://twntyx.netlify.app/images/prototype/design-system-cover.webp)
 
 👉 A **CSS Framework** built on [Tailwind CSS](https://www.npmjs.com/package/tailwindcss) to bring consistency and speed to **twntyX products**.
 
@@ -86,6 +86,21 @@ Available machine-readable exports:
 
 Maintenance workflow for keeping this metadata current lives in `LLM_MAINTENANCE.md`.
 
+## Assistant guides (Codex + Claude, no skills)
+
+The package also includes tool-native guidance files that tell coding assistants to use the canonical `twntyx-css/llm/*` metadata contract.
+
+- `node_modules/twntyx-css/llm/assistants/codex/AGENTS.md`
+- `node_modules/twntyx-css/llm/assistants/claude/CLAUDE.md`
+- `node_modules/twntyx-css/llm/assistants/README.md`
+
+Copy into your consumer repo:
+
+```bash
+cp node_modules/twntyx-css/llm/assistants/codex/AGENTS.md ./AGENTS.md
+cp node_modules/twntyx-css/llm/assistants/claude/CLAUDE.md ./CLAUDE.md
+```
+
 ## Publishing
 
 From the repository root:

package/llm/assistants/README.md

@@ -0,0 +1,28 @@
+# Assistant Guides (No Skills)
+
+Use these templates to configure Codex and Claude Code to follow the canonical twntyx-css metadata contract.
+
+## Available Templates
+- `./codex/AGENTS.md`
+- `./claude/CLAUDE.md`
+
+## Copy Into a Consumer Repo
+Codex:
+```bash
+cp node_modules/twntyx-css/llm/assistants/codex/AGENTS.md ./AGENTS.md
+```
+
+Claude Code:
+```bash
+cp node_modules/twntyx-css/llm/assistants/claude/CLAUDE.md ./CLAUDE.md
+```
+
+## Canonical Package Metadata Paths
+- `node_modules/twntyx-css/llm/index.json`
+- `node_modules/twntyx-css/llm/rules.json`
+- `node_modules/twntyx-css/llm/components/<id>.json`
+- `node_modules/twntyx-css/llm/tokens.json`
+- `node_modules/twntyx-css/llm/patterns.json`
+- `node_modules/twntyx-css/llm/schema.json`
+
+No skills are required for this setup.

package/llm/assistants/claude/CLAUDE.md

@@ -0,0 +1,48 @@
+# twntyx-css Metadata Contract (Claude Code, No Skills)
+
+Generated from `twntyx-css/llm/index.json` and `twntyx-css/llm/rules.json`. Do not hand-edit.
+
+Use the installed package metadata as the single source of truth:
+
+- `node_modules/twntyx-css/llm/index.json`
+- `node_modules/twntyx-css/llm/rules.json`
+- `node_modules/twntyx-css/llm/components/<id>.json`
+- `node_modules/twntyx-css/llm/tokens.json`
+- `node_modules/twntyx-css/llm/patterns.json`
+- `node_modules/twntyx-css/llm/schema.json`
+
+Programmatic import paths:
+- `twntyx-css/llm`
+- `twntyx-css/llm/components/<id>.json`
+- `twntyx-css/llm/tokens`
+- `twntyx-css/llm/patterns`
+- `twntyx-css/llm/rules`
+
+## Component Lookup Workflow
+1. Load `twntyx-css/llm` (`index.json`).
+2. Resolve component using priority: `id -> name -> keywords`.
+3. Load `twntyx-css/llm/components/<id>.json`.
+4. Generate minimal valid HTML first, then layer only documented variants/sizes/states.
+5. Enforce `a11y`, `dos`, `donts`, and `tokenUsage` exactly.
+
+## Unknown Component Contract
+If no supported component matches, return:
+- `code`: `UNSUPPORTED_COMPONENT`
+- `message`: "The requested component is not part of this design-system contract. Use index.json to find the nearest supported component."
+- `suggestedActions`: use `queryBehavior.unsupportedComponent.suggestedActions` from `twntyx-css/llm`.
+
+## Hard Constraints
+Do:
+- Use component base classes exactly as documented in component metadata.
+- Prefer semantic token classes (`text-*`, `bg-*`, `line-*`) for color intent.
+- Generate minimal valid HTML before layering variants and states.
+
+Don't:
+- Do not invent undocumented classes or variant names.
+- Do not remove accessibility attributes from interactive elements.
+- Do not mix conflicting state classes on one root element.
+
+## Output Requirements
+- Never invent classes, variants, attributes, roles, or ARIA requirements.
+- Prefer stable components when multiple matches are possible.
+- Include a short compliance note that cites critical a11y and token decisions.

package/llm/assistants/codex/AGENTS.md

@@ -0,0 +1,48 @@
+# twntyx-css Metadata Contract (Codex, No Skills)
+
+Generated from `twntyx-css/llm/index.json` and `twntyx-css/llm/rules.json`. Do not hand-edit.
+
+Use the installed package metadata as the single source of truth:
+
+- `node_modules/twntyx-css/llm/index.json`
+- `node_modules/twntyx-css/llm/rules.json`
+- `node_modules/twntyx-css/llm/components/<id>.json`
+- `node_modules/twntyx-css/llm/tokens.json`
+- `node_modules/twntyx-css/llm/patterns.json`
+- `node_modules/twntyx-css/llm/schema.json`
+
+Programmatic import paths:
+- `twntyx-css/llm`
+- `twntyx-css/llm/components/<id>.json`
+- `twntyx-css/llm/tokens`
+- `twntyx-css/llm/patterns`
+- `twntyx-css/llm/rules`
+
+## Component Lookup Workflow
+1. Load `twntyx-css/llm` (`index.json`).
+2. Resolve component using priority: `id -> name -> keywords`.
+3. Load `twntyx-css/llm/components/<id>.json`.
+4. Generate minimal valid HTML first, then layer only documented variants/sizes/states.
+5. Enforce `a11y`, `dos`, `donts`, and `tokenUsage` exactly.
+
+## Unknown Component Contract
+If no supported component matches, return:
+- `code`: `UNSUPPORTED_COMPONENT`
+- `message`: "The requested component is not part of this design-system contract. Use index.json to find the nearest supported component."
+- `suggestedActions`: use `queryBehavior.unsupportedComponent.suggestedActions` from `twntyx-css/llm`.
+
+## Hard Constraints
+Do:
+- Use component base classes exactly as documented in component metadata.
+- Prefer semantic token classes (`text-*`, `bg-*`, `line-*`) for color intent.
+- Generate minimal valid HTML before layering variants and states.
+
+Don't:
+- Do not invent undocumented classes or variant names.
+- Do not remove accessibility attributes from interactive elements.
+- Do not mix conflicting state classes on one root element.
+
+## Output Requirements
+- Never invent classes, variants, attributes, roles, or ARIA requirements.
+- Prefer stable components when multiple matches are possible.
+- Include a short compliance note that cites critical a11y and token decisions.

package/llm/components/chat-ai.json

@@ -0,0 +1,89 @@
+{
+  "id": "chat-ai",
+  "name": "AI chat structure",
+  "status": "stable",
+  "summary": "AI chat conversation patterns with text, media, MCP bubbles, loading, and assistant response loop simulations.",
+  "keywords": [
+    "ai chat",
+    "assistant",
+    "chat",
+    "chat ai",
+    "chat-ai",
+    "chatbot",
+    "loading state",
+    "mcp fallback",
+    "mcp result",
+    "mcp tool action",
+    "new message state"
+  ],
+  "sourcePaths": [
+    "app/design-system/chat-ai/page.js"
+  ],
+  "apiModel": "html-class",
+  "baseClass": "chat-ai",
+  "variants": [],
+  "sizes": [],
+  "states": [],
+  "structure": {
+    "rootElement": "div",
+    "requiredClasses": [
+      "chat-ai"
+    ],
+    "optionalClasses": [],
+    "requiredChildren": [],
+    "optionalChildren": []
+  },
+  "attributes": {
+    "allowed": [
+      "class"
+    ],
+    "required": [],
+    "dataAttributes": [
+      "data-loading"
+    ],
+    "roles": [
+      "status"
+    ],
+    "aria": [
+      "aria-label"
+    ]
+  },
+  "a11y": {
+    "interactive": false,
+    "requiredRoles": [
+      "status"
+    ],
+    "requiredAria": [
+      "aria-label"
+    ],
+    "keyboardSupport": [],
+    "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
+  },
+  "dos": [
+    "Apply the base class 'chat-ai' on the root element.",
+    "Use documented modifiers for visual variants instead of ad-hoc custom classes.",
+    "Keep semantic color usage aligned with token classes for light/dark support."
+  ],
+  "donts": [
+    "Do not combine conflicting state classes on the same element.",
+    "Do not rely on undocumented internal classes in production templates.",
+    "Do not remove required accessibility attributes when component is interactive."
+  ],
+  "tokenUsage": [],
+  "examples": [
+    {
+      "id": "canonical",
+      "file": "examples/chat-ai.html",
+      "description": "Minimal canonical AI chat structure usage."
+    }
+  ],
+  "composition": {
+    "patterns": [],
+    "relatedComponents": [],
+    "notes": []
+  },
+  "breakingChangePolicy": {
+    "classContract": "Base class, documented modifiers, and state class names are semver-protected for consumer markup.",
+    "a11yContract": "Documented role and aria requirements are semver-protected for generated markup."
+  }
+}

package/llm/components/chat-footer.json

@@ -0,0 +1,99 @@
+{
+  "id": "chat-footer",
+  "name": "Chat footer",
+  "status": "stable",
+  "summary": "Chat composer/footer patterns including the current footer and a full variant with file upload trigger, model selector, and dictation simulation.",
+  "keywords": [
+    "attachment",
+    "chat",
+    "chat footer",
+    "chat input",
+    "chat-footer",
+    "composer",
+    "dictation",
+    "footer",
+    "ghost select",
+    "model selector"
+  ],
+  "sourcePaths": [
+    "app/design-system/chat-footer/page.js",
+    "assets/styles/chat.css",
+    "assets/styles/panel.css"
+  ],
+  "apiModel": "html-class",
+  "baseClass": "chat-footer",
+  "variants": [],
+  "sizes": [],
+  "states": [],
+  "structure": {
+    "rootElement": "div",
+    "requiredClasses": [
+      "chat-footer"
+    ],
+    "optionalClasses": [],
+    "requiredChildren": [],
+    "optionalChildren": []
+  },
+  "attributes": {
+    "allowed": [
+      "class"
+    ],
+    "required": [],
+    "dataAttributes": [],
+    "roles": [],
+    "aria": [
+      "aria-label"
+    ]
+  },
+  "a11y": {
+    "interactive": false,
+    "requiredRoles": [],
+    "requiredAria": [
+      "aria-label"
+    ],
+    "keyboardSupport": [],
+    "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
+  },
+  "dos": [
+    "Apply the base class 'chat-footer' on the root element.",
+    "Use documented modifiers for visual variants instead of ad-hoc custom classes.",
+    "Keep semantic color usage aligned with token classes for light/dark support."
+  ],
+  "donts": [
+    "Do not combine conflicting state classes on the same element.",
+    "Do not rely on undocumented internal classes in production templates.",
+    "Do not remove required accessibility attributes when component is interactive."
+  ],
+  "tokenUsage": [
+    "background-error",
+    "background-page",
+    "background-surface",
+    "background-surface-elevated",
+    "background-surface-sunken",
+    "core-black",
+    "core-white",
+    "line-default",
+    "line-strong",
+    "text-default",
+    "text-link",
+    "text-link-hover",
+    "text-secondary",
+    "text-tertiary"
+  ],
+  "examples": [
+    {
+      "id": "canonical",
+      "file": "examples/chat-footer.html",
+      "description": "Minimal canonical Chat footer usage."
+    }
+  ],
+  "composition": {
+    "patterns": [],
+    "relatedComponents": [],
+    "notes": []
+  },
+  "breakingChangePolicy": {
+    "classContract": "Base class, documented modifiers, and state class names are semver-protected for consumer markup.",
+    "a11yContract": "Documented role and aria requirements are semver-protected for generated markup."
+  }
+}

package/llm/components/chat-person-to-person.json

@@ -0,0 +1,157 @@
+{
+  "id": "chat-person-to-person",
+  "name": "Person to person chat structure",
+  "status": "stable",
+  "summary": "Conversation patterns between people, including text, image attachments, MCP content, loading and new-message simulation states.",
+  "keywords": [
+    "chat",
+    "chat person to person",
+    "chat structure",
+    "chat-person-to-person",
+    "conversation",
+    "human chat",
+    "loading state",
+    "mcp",
+    "message attachments",
+    "messages",
+    "person to person"
+  ],
+  "sourcePaths": [
+    "app/design-system/chat-person-to-person/page.js",
+    "assets/styles/button.css",
+    "assets/styles/chat.css",
+    "assets/styles/form-text-select.css",
+    "assets/styles/panel.css",
+    "assets/styles/toast.css"
+  ],
+  "apiModel": "html-class",
+  "baseClass": "chat",
+  "variants": [],
+  "sizes": [],
+  "states": [
+    {
+      "name": "is-owner",
+      "className": "is-owner",
+      "description": "Indicates messages from the current user"
+    },
+    {
+      "name": "is-loading",
+      "className": "is-loading",
+      "description": "Loading state that reveals"
+    }
+  ],
+  "structure": {
+    "rootElement": "div",
+    "requiredClasses": [
+      "chat"
+    ],
+    "optionalClasses": [
+      "is-owner",
+      "is-loading"
+    ],
+    "requiredChildren": [],
+    "optionalChildren": []
+  },
+  "attributes": {
+    "allowed": [
+      "class"
+    ],
+    "required": [],
+    "dataAttributes": [
+      "data-loading"
+    ],
+    "roles": [
+      "status"
+    ],
+    "aria": [
+      "aria-label"
+    ]
+  },
+  "a11y": {
+    "interactive": false,
+    "requiredRoles": [
+      "status"
+    ],
+    "requiredAria": [
+      "aria-label"
+    ],
+    "keyboardSupport": [],
+    "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
+  },
+  "dos": [
+    "Apply the base class 'chat' on the root element.",
+    "Use documented modifiers for visual variants instead of ad-hoc custom classes.",
+    "Keep semantic color usage aligned with token classes for light/dark support."
+  ],
+  "donts": [
+    "Do not combine conflicting state classes on the same element.",
+    "Do not rely on undocumented internal classes in production templates.",
+    "Do not remove required accessibility attributes when component is interactive."
+  ],
+  "tokenUsage": [
+    "background-brand",
+    "background-brand-active",
+    "background-error",
+    "background-error-active",
+    "background-info",
+    "background-info-active",
+    "background-inverted",
+    "background-page",
+    "background-success",
+    "background-success-active",
+    "background-surface",
+    "background-surface-elevated",
+    "background-surface-sunken",
+    "background-warning",
+    "background-warning-active",
+    "brand-default",
+    "brand-moderate",
+    "brand-strong",
+    "core-black",
+    "core-ui-100",
+    "core-ui-50",
+    "core-ui-700",
+    "core-ui-800",
+    "core-ui-900",
+    "core-white",
+    "line-default",
+    "line-error",
+    "line-focus",
+    "line-highlight",
+    "line-info",
+    "line-strong",
+    "line-success",
+    "line-warning",
+    "text-attention",
+    "text-brand",
+    "text-brand-active",
+    "text-brand-hover",
+    "text-default",
+    "text-disabled",
+    "text-error",
+    "text-info",
+    "text-inverted",
+    "text-link",
+    "text-link-hover",
+    "text-secondary",
+    "text-success",
+    "text-tertiary",
+    "text-warning"
+  ],
+  "examples": [
+    {
+      "id": "canonical",
+      "file": "examples/chat-person-to-person.html",
+      "description": "Minimal canonical Person to person chat structure usage."
+    }
+  ],
+  "composition": {
+    "patterns": [],
+    "relatedComponents": [],
+    "notes": []
+  },
+  "breakingChangePolicy": {
+    "classContract": "Base class, documented modifiers, and state class names are semver-protected for consumer markup.",
+    "a11yContract": "Documented role and aria requirements are semver-protected for generated markup."
+  }
+}

package/llm/components/chat.json

@@ -1,56 +1,27 @@
 {
   "id": "chat",
   "name": "Chat",
-  "status": "stable",
-  "summary": "Chat component for displaying conversations between users or with AI assistants.",
+  "status": "preview",
+  "summary": "Documentation and contract metadata for Chat in the twntyX design system.",
   "keywords": [
-    "ai chat",
-    "chat",
-    "chatbot",
-    "communication",
-    "conversation",
-    "messages"
+    "chat"
   ],
   "sourcePaths": [
     "app/design-system/chat/page.js",
-    "assets/styles/button.css",
     "assets/styles/chat.css",
-    "assets/styles/form-text-select.css",
-    "assets/styles/panel.css",
-    "assets/styles/toast.css"
+    "assets/styles/panel.css"
   ],
   "apiModel": "html-class",
   "baseClass": "chat",
-  "variants": [
-    {
-      "name": "chat-secondary",
-      "className": "chat-secondary",
-      "description": "Alternative styling for AI chat"
-    }
-  ],
+  "variants": [],
   "sizes": [],
-  "states": [
-    {
-      "name": "is-owner",
-      "className": "is-owner",
-      "description": "Indicates messages from the current user"
-    },
-    {
-      "name": "is-loading",
-      "className": "is-loading",
-      "description": "Loading state that reveals"
-    }
-  ],
+  "states": [],
   "structure": {
     "rootElement": "div",
     "requiredClasses": [
       "chat"
     ],
-    "optionalClasses": [
-      "chat-secondary",
-      "is-owner",
-      "is-loading"
-    ],
+    "optionalClasses": [],
     "requiredChildren": [],
     "optionalChildren": []
   },
@@ -59,19 +30,13 @@
       "class"
     ],
     "required": [],
-    "dataAttributes": [
-      "data-loading"
-    ],
-    "roles": [
-      "status"
-    ],
+    "dataAttributes": [],
+    "roles": [],
     "aria": []
   },
   "a11y": {
     "interactive": false,
-    "requiredRoles": [
-      "status"
-    ],
+    "requiredRoles": [],
     "requiredAria": [],
     "keyboardSupport": [],
     "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
@@ -87,54 +52,20 @@
     "Do not remove required accessibility attributes when component is interactive."
   ],
   "tokenUsage": [
-    "background-brand",
-    "background-brand-active",
     "background-error",
-    "background-error-active",
-    "background-info",
-    "background-info-active",
-    "background-inverted",
     "background-page",
-    "background-success",
-    "background-success-active",
     "background-surface",
     "background-surface-elevated",
     "background-surface-sunken",
-    "background-warning",
-    "background-warning-active",
-    "brand-default",
-    "brand-moderate",
-    "brand-strong",
     "core-black",
-    "core-ui-100",
-    "core-ui-50",
-    "core-ui-700",
-    "core-ui-800",
-    "core-ui-900",
     "core-white",
     "line-default",
-    "line-error",
-    "line-focus",
-    "line-highlight",
-    "line-info",
     "line-strong",
-    "line-success",
-    "line-warning",
-    "text-attention",
-    "text-brand",
-    "text-brand-active",
-    "text-brand-hover",
     "text-default",
-    "text-disabled",
-    "text-error",
-    "text-info",
-    "text-inverted",
     "text-link",
     "text-link-hover",
     "text-secondary",
-    "text-success",
-    "text-tertiary",
-    "text-warning"
+    "text-tertiary"
   ],
   "examples": [
     {