twntyx-css 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+![twntyX CSS Framework](/images/logos/stryda-logo-dark-png.png)
+
+👉 A **CSS Framework** built on [Tailwind CSS](https://www.npmjs.com/package/tailwindcss) to bring consistency and speed to **twntyX products**.
+
+------
+
+## Documentation
+
+For full documentation, visit [twntyX.netlify.app](https://twntyX.netlify.app/).
+
+## Using the framework
+
+### 1. Install tailwindcss
+
+Install tailwindcss and its peer dependencies via npm.
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+```
+
+### 2. Install the framework
+
+Install twntyx-css via npm.
+
+```bash
+npm install twntyx-css
+```
+
+### 3. Import the css
+
+Import the Framework CSS into your project stylesheet.
+
+```css
+@import 'twntyx-css/styles/globals.css';
+```
+
+### 4. Adapt webpack config.
+
+Add postcss-loader to webpack.config.js.
+
+```js
+module: {
+  rules: [
+    {
+      test: /\.(css)$/,
+      use: ['style-loader', 'css-loader', 'postcss-loader'],
+    }
+  ]
+}
+```
+
+### 5. Import and adapt tailwind config.
+
+Import the framework config into your project tailwind.config.js and indicate which files Tailwind should scan.
+
+```js
+const tailwindConfig = require('twntyx-css/tailwind.config');
+module.exports = {
+  ...tailwindConfig,
+  content: [
+    "./pages/*.{js,ts,jsx,tsx,json}",
+  ],
+};
+```
+
+## LLM metadata kit
+
+The package ships machine-readable design-system metadata for coding assistants.
+
+```bash
+npm install twntyx-css
+```
+
+```js
+import manifest from "twntyx-css/llm";
+import buttonSpec from "twntyx-css/llm/components/button.json";
+```
+
+Available machine-readable exports:
+
+- `twntyx-css/llm`
+- `twntyx-css/llm/components/*`
+- `twntyx-css/llm/tokens`
+- `twntyx-css/llm/patterns`
+- `twntyx-css/llm/rules`
+
+Maintenance workflow for keeping this metadata current lives in `LLM_MAINTENANCE.md`.
+
+## Publishing
+
+From the repository root:
+
+```bash
+npm run pack:framework
+```
+
+When ready to publish:
+
+```bash
+npm run publish:framework
+```
+
+## That's it!
+
+Your projects can now consume the twntyX theme and components. ✨

package/llm/CHANGELOG.md

@@ -0,0 +1,7 @@
+# LLM Kit Changelog
+
+All notable changes to the generated LLM metadata contract are documented in this file.
+
+## [1.0.0] - 2026-02-22
+- Initial machine-readable LLM kit release.
+- Added schema, component contracts, tokens, composition patterns, and global rules.

package/llm/components/ai-background.json

@@ -0,0 +1,90 @@
+{
+  "id": "ai-background",
+  "name": "Background",
+  "status": "stable",
+  "summary": "AI background is a twntyX branded background for AI experiences with animated gradients.",
+  "keywords": [
+    "agent",
+    "ai",
+    "ai background",
+    "ai-background",
+    "background",
+    "background blur",
+    "blur",
+    "blur background",
+    "chat",
+    "gpt",
+    "llama",
+    "llm",
+    "openai",
+    "twntyX"
+  ],
+  "sourcePaths": [
+    "app/design-system/ai-background/page.js",
+    "assets/styles/background-ai.css"
+  ],
+  "apiModel": "html-class",
+  "baseClass": "background-ai-silk",
+  "variants": [],
+  "sizes": [],
+  "states": [],
+  "structure": {
+    "rootElement": "div",
+    "requiredClasses": [
+      "background-ai-silk"
+    ],
+    "optionalClasses": [],
+    "requiredChildren": [],
+    "optionalChildren": []
+  },
+  "attributes": {
+    "allowed": [
+      "class"
+    ],
+    "required": [],
+    "dataAttributes": [],
+    "roles": [],
+    "aria": []
+  },
+  "a11y": {
+    "interactive": false,
+    "requiredRoles": [],
+    "requiredAria": [],
+    "keyboardSupport": [],
+    "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
+  },
+  "dos": [
+    "Apply the base class 'background-ai-silk' 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": [
+    "brand-default",
+    "brand-light",
+    "brand-moderate",
+    "brand-soft",
+    "core-black",
+    "core-white"
+  ],
+  "examples": [
+    {
+      "id": "canonical",
+      "file": "examples/ai-background.html",
+      "description": "Minimal canonical Background 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/ai-orb.json

@@ -0,0 +1,91 @@
+{
+  "id": "ai-orb",
+  "name": "Orb",
+  "status": "stable",
+  "summary": "Ambient AI orb with layered conic gradients and soft glow.",
+  "keywords": [
+    "ai",
+    "ai orb",
+    "ai-orb",
+    "ambient",
+    "animation",
+    "background",
+    "glow",
+    "orb",
+    "sphere"
+  ],
+  "sourcePaths": [
+    "app/design-system/ai-orb/page.js",
+    "assets/styles/ai.css"
+  ],
+  "apiModel": "html-class",
+  "baseClass": "ai-orb",
+  "variants": [],
+  "sizes": [],
+  "states": [],
+  "structure": {
+    "rootElement": "div",
+    "requiredClasses": [
+      "ai-orb"
+    ],
+    "optionalClasses": [],
+    "requiredChildren": [],
+    "optionalChildren": []
+  },
+  "attributes": {
+    "allowed": [
+      "class"
+    ],
+    "required": [],
+    "dataAttributes": [],
+    "roles": [],
+    "aria": []
+  },
+  "a11y": {
+    "interactive": false,
+    "requiredRoles": [],
+    "requiredAria": [],
+    "keyboardSupport": [],
+    "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
+  },
+  "dos": [
+    "Apply the base class 'ai-orb' 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": [
+    "brand-default",
+    "brand-light",
+    "brand-moderate",
+    "brand-soft",
+    "core-black",
+    "core-ui-300",
+    "core-ui-400",
+    "core-ui-500",
+    "core-ui-600",
+    "core-white",
+    "text-default",
+    "text-inverted"
+  ],
+  "examples": [
+    {
+      "id": "canonical",
+      "file": "examples/ai-orb.html",
+      "description": "Minimal canonical Orb 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/ai-perl.json

@@ -0,0 +1,91 @@
+{
+  "id": "ai-perl",
+  "name": "Perl",
+  "status": "stable",
+  "summary": "Animated AI loader with circular glow ring and letter pulse.",
+  "keywords": [
+    "ai",
+    "ai perl",
+    "ai-perl",
+    "animation",
+    "generating",
+    "loading",
+    "overlay",
+    "perl",
+    "spinner"
+  ],
+  "sourcePaths": [
+    "app/design-system/ai-perl/page.js",
+    "assets/styles/ai.css"
+  ],
+  "apiModel": "html-class",
+  "baseClass": "ai-perl",
+  "variants": [],
+  "sizes": [],
+  "states": [],
+  "structure": {
+    "rootElement": "div",
+    "requiredClasses": [
+      "ai-perl"
+    ],
+    "optionalClasses": [],
+    "requiredChildren": [],
+    "optionalChildren": []
+  },
+  "attributes": {
+    "allowed": [
+      "class"
+    ],
+    "required": [],
+    "dataAttributes": [],
+    "roles": [],
+    "aria": []
+  },
+  "a11y": {
+    "interactive": false,
+    "requiredRoles": [],
+    "requiredAria": [],
+    "keyboardSupport": [],
+    "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
+  },
+  "dos": [
+    "Apply the base class 'ai-perl' 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": [
+    "brand-default",
+    "brand-light",
+    "brand-moderate",
+    "brand-soft",
+    "core-black",
+    "core-ui-300",
+    "core-ui-400",
+    "core-ui-500",
+    "core-ui-600",
+    "core-white",
+    "text-default",
+    "text-inverted"
+  ],
+  "examples": [
+    {
+      "id": "canonical",
+      "file": "examples/ai-perl.html",
+      "description": "Minimal canonical Perl 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/all-components.json

@@ -0,0 +1,104 @@
+{
+  "id": "all-components",
+  "name": "All components",
+  "status": "stable",
+  "summary": "Overview of all available components with live examples.",
+  "keywords": [
+    "all components",
+    "all-components",
+    "catalog",
+    "collection",
+    "components",
+    "demo",
+    "docs",
+    "documentation",
+    "elements",
+    "examples",
+    "gallery",
+    "guide",
+    "index",
+    "interface",
+    "library",
+    "list",
+    "overview",
+    "preview",
+    "reference",
+    "sample",
+    "showcase",
+    "ui"
+  ],
+  "sourcePaths": [
+    "app/design-system/all-components/page.js"
+  ],
+  "apiModel": "html-class",
+  "baseClass": "all-components",
+  "variants": [],
+  "sizes": [],
+  "states": [],
+  "structure": {
+    "rootElement": "div",
+    "requiredClasses": [
+      "all-components"
+    ],
+    "optionalClasses": [],
+    "requiredChildren": [],
+    "optionalChildren": []
+  },
+  "attributes": {
+    "allowed": [
+      "class"
+    ],
+    "required": [],
+    "dataAttributes": [
+      "data-value"
+    ],
+    "roles": [
+      "separator",
+      "status"
+    ],
+    "aria": [
+      "aria-current",
+      "aria-label"
+    ]
+  },
+  "a11y": {
+    "interactive": false,
+    "requiredRoles": [
+      "separator",
+      "status"
+    ],
+    "requiredAria": [
+      "aria-current",
+      "aria-label"
+    ],
+    "keyboardSupport": [],
+    "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
+  },
+  "dos": [
+    "Apply the base class 'all-components' 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/all-components.html",
+      "description": "Minimal canonical All components 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/animation-references.json

@@ -0,0 +1,84 @@
+{
+  "id": "animation-references",
+  "name": "Animation references",
+  "status": "stable",
+  "summary": "Browse and preview all available CSS animations from the design system. Includes entrance, exit, and infinite loop animations with live previews and copy-to-clipboard functionality.",
+  "keywords": [
+    "animation",
+    "animation references",
+    "animation-references",
+    "bounce",
+    "css animation",
+    "effect",
+    "entrance",
+    "exit",
+    "fade",
+    "float",
+    "keyframes",
+    "motion",
+    "rotate",
+    "scale",
+    "slide",
+    "transition"
+  ],
+  "sourcePaths": [
+    "app/design-system/animation-references/page.js"
+  ],
+  "apiModel": "html-class",
+  "baseClass": "animation-references",
+  "variants": [],
+  "sizes": [],
+  "states": [],
+  "structure": {
+    "rootElement": "div",
+    "requiredClasses": [
+      "animation-references"
+    ],
+    "optionalClasses": [],
+    "requiredChildren": [],
+    "optionalChildren": []
+  },
+  "attributes": {
+    "allowed": [
+      "class"
+    ],
+    "required": [],
+    "dataAttributes": [],
+    "roles": [],
+    "aria": []
+  },
+  "a11y": {
+    "interactive": false,
+    "requiredRoles": [],
+    "requiredAria": [],
+    "keyboardSupport": [],
+    "focusBehavior": "No keyboard interaction is required unless nested interactive children are introduced."
+  },
+  "dos": [
+    "Apply the base class 'animation-references' 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/animation-references.html",
+      "description": "Minimal canonical Animation references 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."
+  }
+}