twntyx-css 1.0.0

package/llm/llms.txt

@@ -0,0 +1,18 @@
+# twntyX CSS Framework LLM Kit
+
+This package ships machine-readable design-system metadata for coding assistants.
+
+- Package: twntyx-css
+- Manifest: ./index.json
+- Schema: ./schema.json
+- Components: ./components/*.json
+- Tokens: ./tokens.json
+- Patterns: ./patterns.json
+- Rules: ./rules.json
+- Canonical HTML Examples: ./examples/*.html
+
+Lookup contract:
+1. Resolve component by id/name/keywords from index.json.
+2. Load component contract from ./components/<id>.json.
+3. Follow dos/donts, a11y constraints, and tokenUsage exactly.
+4. If not found, return the unsupportedComponent payload from index.json.

package/llm/patterns.json

@@ -0,0 +1,111 @@
+{
+  "llmSchemaVersion": "1.0.0",
+  "patterns": [
+    {
+      "id": "form-field-composition",
+      "name": "Field + Control + Validation",
+      "summary": "Compose input-like controls with labels, helper text, and validation states.",
+      "components": [
+        "field",
+        "text-input",
+        "textarea",
+        "select-input",
+        "checkbox",
+        "radio",
+        "combobox"
+      ],
+      "template": "Wrap each control in `.field`, render `.input-label` first, and keep helper/error copy directly under the control.",
+      "dos": [
+        "Place labels before controls.",
+        "Include helper text for format-sensitive fields."
+      ],
+      "donts": [
+        "Do not rely on placeholders as labels.",
+        "Do not hide validation reason text."
+      ]
+    },
+    {
+      "id": "feedback-and-status",
+      "name": "Feedback Layering",
+      "summary": "Pick transient vs persistent feedback patterns based on severity and blocking behavior.",
+      "components": [
+        "banner",
+        "toast",
+        "state",
+        "modal",
+        "button"
+      ],
+      "template": "Use toast for transient success/info, banner/state for persistent contextual feedback, and modal for blocking decisions.",
+      "dos": [
+        "Escalate severity progressively.",
+        "Keep one clear next action for blocking feedback."
+      ],
+      "donts": [
+        "Do not stack multiple blocking dialogs.",
+        "Do not use toasts for critical failures requiring confirmation."
+      ]
+    },
+    {
+      "id": "table-data-disclosure",
+      "name": "Data Table + Pagination",
+      "summary": "Pattern for scanning and acting on structured data sets.",
+      "components": [
+        "table",
+        "pagination",
+        "checkbox",
+        "button"
+      ],
+      "template": "Render sortable headers, keep row selection explicit, and place pagination controls adjacent to the table footer.",
+      "dos": [
+        "Expose sorting state textually and visually.",
+        "Keep row actions discoverable on focus and hover."
+      ],
+      "donts": [
+        "Do not paginate without preserving filters/sort state.",
+        "Do not encode row status only by color."
+      ]
+    },
+    {
+      "id": "navigation-hierarchy",
+      "name": "Navigation Hierarchy",
+      "summary": "Coordinate global and local navigation primitives.",
+      "components": [
+        "navbar",
+        "menu",
+        "breadcrumb",
+        "tabs",
+        "link"
+      ],
+      "template": "Use navbar for global sections, breadcrumb for hierarchy, and tabs/menu for local context switching.",
+      "dos": [
+        "Keep active location unambiguous.",
+        "Preserve keyboard navigation across all items."
+      ],
+      "donts": [
+        "Do not duplicate the same hierarchy level in multiple nav patterns.",
+        "Do not remove semantic link/button elements from interactive nav items."
+      ]
+    },
+    {
+      "id": "surface-and-content",
+      "name": "Surface + Content Blocks",
+      "summary": "Create coherent content groups using surface, card, and lightweight status elements.",
+      "components": [
+        "surface",
+        "card",
+        "badge",
+        "avatar",
+        "divider"
+      ],
+      "template": "Start with a surface layer, then place card content blocks and optional badges for status emphasis.",
+      "dos": [
+        "Keep vertical spacing rhythm consistent.",
+        "Use badges for short, non-blocking state cues."
+      ],
+      "donts": [
+        "Do not combine conflicting elevation styles in one container.",
+        "Do not turn decorative badges into primary action controls."
+      ]
+    }
+  ]
+}

package/llm/rules.json

@@ -0,0 +1,47 @@
+{
+  "llmSchemaVersion": "1.0.0",
+  "apiModel": "html-class",
+  "dos": [
+    "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."
+  ],
+  "donts": [
+    "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."
+  ],
+  "accessibility": [
+    "Interactive primitives must be keyboard reachable and visibly focused.",
+    "Validation and status must not be conveyed by color alone.",
+    "Use native semantics first; add ARIA only when required by behavior."
+  ],
+  "namingConventions": {
+    "classPrefixes": [
+      "button",
+      "badge",
+      "card",
+      "modal",
+      "table",
+      "surface",
+      "input",
+      "toast",
+      "menu"
+    ],
+    "statePrefixes": [
+      "is-",
+      "has-"
+    ],
+    "sizeMarkers": [
+      "-xs",
+      "-sm",
+      "-md",
+      "-lg",
+      "-xl"
+    ]
+  },
+  "responseContract": {
+    "whenUnknown": "Return UNSUPPORTED_COMPONENT from index.json and suggest nearest stable matches.",
+    "whenAmbiguous": "Prefer stable components and produce the smallest canonical markup that satisfies requirements."
+  }
+}