{"id":29509177,"url":"https://github.com/tokens-studio/sd-tailwindv4","last_synced_at":"2025-07-16T06:09:33.944Z","repository":{"id":302657595,"uuid":"987170762","full_name":"tokens-studio/sd-tailwindv4","owner":"tokens-studio","description":"Example of a style-dictionary workflow implementation to Tailwind V4","archived":false,"fork":false,"pushed_at":"2025-07-03T15:09:20.000Z","size":166,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-03T15:29:45.150Z","etag":null,"topics":["design-tokens","style-dictionary","tailwindcss","tailwindcss-v4"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tokens-studio.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-20T17:19:05.000Z","updated_at":"2025-07-03T15:23:39.000Z","dependencies_parsed_at":"2025-07-03T15:40:41.218Z","dependency_job_id":null,"html_url":"https://github.com/tokens-studio/sd-tailwindv4","commit_stats":null,"previous_names":["tokens-studio/sd-tailwindv4"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tokens-studio/sd-tailwindv4","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokens-studio%2Fsd-tailwindv4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokens-studio%2Fsd-tailwindv4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokens-studio%2Fsd-tailwindv4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokens-studio%2Fsd-tailwindv4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tokens-studio","download_url":"https://codeload.github.com/tokens-studio/sd-tailwindv4/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokens-studio%2Fsd-tailwindv4/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265487239,"owners_count":23774835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design-tokens","style-dictionary","tailwindcss","tailwindcss-v4"],"created_at":"2025-07-16T06:09:33.263Z","updated_at":"2025-07-16T06:09:33.917Z","avatar_url":"https://github.com/tokens-studio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tailwind v4 TypeScript Configuration Tool\n\nA powerful, type-safe design token pipeline that transforms JSON design tokens into Tailwind v4 CSS using Style Dictionary. Built with TypeScript for enhanced developer experience and robust configuration management.\n\n\u003e [!NOTE] \n\u003e There are some patterns in the JSON format that don't align appropriately with the DTGC or expected Style Dictionary format. This is an exploration and experiment into what is possible and how tokens can be structured and processed.\n\n\n## 🎯 Features\n\n- **🔷 TypeScript-First**: Fully typed configuration with IntelliSense support\n- **⚡ Fast Builds**: Optimized compilation and token processing\n- **🎨 Theme Support**: Advanced theming with automatic dark/light mode\n- **🧩 Component Tokens**: Pre-built component styles and utilities\n- **🔧 Extensible**: Custom processors, transforms, and configurations\n- **📦 Modular Architecture**: Clean separation between source and runtime\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\nnpm install\n```\n\n### Build \u0026 Run\n\n```bash\n# Full build (TypeScript + tokens)\nnpm run build\n\n# Start development server\nnpm run dev\n\n# Build tokens only\nnpm run build-tokens\n```\n\n## 📁 Project Structure\n\n```\n├── config/                 # TypeScript source files\n│   ├── types.ts            # Type definitions\n│   ├── configuration.ts    # Main configuration class\n│   ├── index.ts           # Plugin entry point\n│   ├── css-builder.ts     # CSS generation utilities\n│   ├── token-engine.ts    # Token processing engine\n│   ├── transforms.ts      # Custom transforms\n│   └── token-processors/  # Individual token processors\n├── tokens/                # Design token JSON files\n├── dist/                  # Compiled JavaScript (auto-generated)\n├── demo/                  # Demo application\n├── config.js             # Runtime configuration\n└── tsconfig.json         # TypeScript configuration\n```\n\n## 🎨 Token Structure\n\nThis tool supports several unconventional but powerful token patterns:\n\n### 1. Theme-Aware Tokens\n\nUse the special `_` property for default values and named variants for themes:\n\n```json\n{\n  \"color\": {\n    \"theme\": {\n      \"content\": {\n        \"_\": { \"$type\": \"color\", \"$value\": \"#000000\" },\n        \"dark\": { \"$type\": \"color\", \"$value\": \"#ffffff\" }\n      },\n      \"background\": {\n        \"_\": { \"$type\": \"color\", \"$value\": \"#ffffff\" },\n        \"dark\": { \"$type\": \"color\", \"$value\": \"#000000\" }\n      }\n    }\n  }\n}\n```\n\n**Generated CSS:**\n```css\n@theme {\n  --color-theme-content: #000000;\n  --color-theme-background: #ffffff;\n}\n\n@layer base {\n  [data-theme=\"dark\"] {\n    --color-theme-content: #ffffff;\n    --color-theme-background: #000000;\n  }\n}\n```\n\n### 2. Component Tokens\n\nDefine complete component styles with pseudo-states:\n\n```json\n{\n  \"component\": {\n    \"button\": {\n      \"primary\": {\n        \"$type\": \"component\",\n        \"$value\": {\n          \"backgroundColor\": \"{color.brand.primary}\",\n          \"color\": \"white\",\n          \"padding\": \"{spacing.3} {spacing.6}\",\n          \"borderRadius\": \"{radius.md}\",\n          \"\u0026:hover\": {\n            \"backgroundColor\": \"{color.blue.600}\",\n            \"transform\": \"translateY(-1px)\"\n          },\n          \"\u0026:focus\": {\n            \"outline\": \"2px solid {color.brand.primary}\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n**Generated CSS:**\n```css\n@layer components {\n  .c-button-primary {\n    background-color: var(--color-brand-primary);\n    color: white;\n    padding: var(--spacing-3) var(--spacing-6);\n    border-radius: var(--radius-md);\n  }\n  \n  .c-button-primary:hover {\n    background-color: var(--color-blue-600);\n    transform: translateY(-1px);\n  }\n  \n  .c-button-primary:focus {\n    outline: 2px solid var(--color-brand-primary);\n  }\n}\n```\n\n### 3. Utility Tokens\n\nCreate custom utility classes:\n\n```json\n{\n  \"utilities\": {\n    \"flex-center\": {\n      \"$type\": \"utility\",\n      \"$value\": {\n        \"display\": \"flex\",\n        \"alignItems\": \"center\",\n        \"justifyContent\": \"center\"\n      }\n    },\n    \"glass\": {\n      \"$type\": \"utility\",\n      \"$value\": {\n        \"backgroundColor\": \"rgba(255, 255, 255, 0.1)\",\n        \"backdropFilter\": \"blur(10px)\",\n        \"border\": \"1px solid rgba(255, 255, 255, 0.2)\"\n      }\n    }\n  }\n}\n```\n\n**Generated CSS:**\n```css\n@utility flex-center {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n\n@utility glass {\n  background-color: rgba(255, 255, 255, 0.1);\n  backdrop-filter: blur(10px);\n  border: 1px solid rgba(255, 255, 255, 0.2);\n}\n```\n\n### 4. Composition Tokens\n\nSimilar to utilities but with enhanced processing:\n\n```json\n{\n  \"utilities\": {\n    \"flex-center\": {\n      \"$type\": \"composition\",\n      \"$value\": {\n        \"display\": \"flex\",\n        \"alignItems\": \"center\",\n        \"justifyContent\": \"center\"\n      }\n    }\n  }\n}\n```\n\n### 5. Animation Tokens\n\nDefine keyframes and transitions:\n\n```json\n{\n  \"animation\": {\n    \"fadeIn\": {\n      \"$type\": \"keyframes\",\n      \"$value\": {\n        \"0%\": { \"opacity\": \"0\" },\n        \"100%\": { \"opacity\": \"1\" }\n      }\n    },\n    \"slideUp\": {\n      \"$type\": \"transition\",\n      \"$value\": {\n        \"property\": \"transform\",\n        \"duration\": \"{duration.fast}\",\n        \"timingFunction\": \"{easing.ease-out}\"\n      }\n    }\n  }\n}\n```\n\n## ⚙️ Configuration\n\n### Basic Configuration (config.js)\n\n```javascript\nimport { createTailwindV4Plugin } from \"./dist/index.js\";\n\nStyleDictionary.registerFormat({\n  name: \"tailwind-v4\",\n  format: createTailwindV4Plugin({\n    // Configuration options\n  })\n});\n```\n\n### Advanced Configuration Options\n\n```javascript\ncreateTailwindV4Plugin({\n  // Theme Configuration\n  themeSelectors: {\n    light: ':root',\n    dark: '[data-theme=\"dark\"]',\n    'high-contrast': '[data-theme=\"high-contrast\"]'\n  },\n\n  // Component Handling\n  componentHandling: {\n    enabled: true,\n    generateUtilities: true,  // Create utility classes from components\n    prefix: 'c-'              // Component class prefix\n  },\n\n  // Utility Generation\n  utilityGeneration: {\n    enabled: true,\n    prefix: 'u-'              // Utility class prefix\n  },\n\n  // Custom Variants\n  customVariants: {\n    'focus-visible': '\u0026:focus-visible',\n    'peer-focus': '.peer:focus ~ \u0026',\n    'group-hover': '.group:hover \u0026'\n  },\n\n  // Token Type Mappings\n  tokenTypeMapping: {\n    'fontSize': 'typography',\n    'fontWeight': 'typography',\n    'shadow': 'shadow',\n    'component': 'component',\n    'utility': 'utility',\n    'composition': 'composition'\n  },\n\n  // Output Options\n  outputOptions: {\n    showComments: true,       // Add comments to generated CSS\n    formatCSS: true,          // Format output CSS\n    groupByLayer: true        // Group by @layer directives\n  }\n})\n```\n\n## 🔧 TypeScript Development\n\n### Type Safety\n\nThe configuration tool provides comprehensive TypeScript support:\n\n```typescript\nimport type { PluginConfig, Token, ProcessedToken } from './config/types.js';\n\n// Strongly typed configuration\nconst config: Partial\u003cPluginConfig\u003e = {\n  themeSelectors: {\n    light: ':root',\n    dark: '.dark'\n  },\n  componentHandling: {\n    enabled: true,\n    generateUtilities: false\n  }\n};\n```\n\n### Custom Processors\n\nCreate custom token processors with full type support:\n\n```typescript\nimport { BaseTokenProcessor } from './config/token-processors/base.js';\nimport type { Token, Dictionary, ProcessedToken } from './config/types.js';\n\nexport class CustomTokenProcessor extends BaseTokenProcessor {\n  canProcess(token: Token): boolean {\n    return token.$type === 'custom';\n  }\n\n  process(token: Token, dictionary: Dictionary): ProcessedToken | null {\n    // Custom processing logic\n    return {\n      type: 'custom',\n      name: `--custom-${token.name}`,\n      value: token.$value\n    };\n  }\n}\n```\n\n## 📝 Token File Conventions\n\n### File Organization\n\nOrganize tokens by category:\n\n```\ntokens/\n├── colors.json          # Color palette and theme colors\n├── typography.json      # Font families, sizes, weights\n├── spacing.json         # Spacing scale\n├── radius.json          # Border radius values\n├── shadows.json         # Box shadow definitions\n├── animations.json      # Keyframes and transitions\n├── components.json      # Component styles\n├── utilities.json       # Custom utility classes\n└── tokens.json          # Core design tokens\n```\n\n### Naming Conventions\n\n- **Kebab-case**: All generated CSS uses kebab-case\n- **Nested structure**: Use object nesting for logical grouping\n- **Theme variants**: Use `_` for default, named keys for variants\n- **Token references**: Use `{path.to.token}` syntax for references\n\n### Special Properties\n\n- **`$type`**: Required - defines the token type\n- **`$value`**: Required - the token value\n- **`$extensions`**: Optional - metadata and extensions\n- **`_` key**: Special key for default theme values\n- **Named keys**: Theme variant names (e.g., `dark`, `light`)\n\n## 🎯 Token Types\n\n| Type | Purpose | Output |\n|------|---------|--------|\n| `color` | Color values | CSS custom properties |\n| `dimension` | Spacing, sizing | CSS custom properties |\n| `fontFamily` | Font stacks | CSS custom properties |\n| `fontSize` | Text sizes | CSS custom properties |\n| `fontWeight` | Font weights | CSS custom properties |\n| `lineHeight` | Line heights | CSS custom properties |\n| `shadow` | Box shadows | CSS custom properties |\n| `component` | Component styles | CSS classes |\n| `utility` | Utility classes | @utility directives |\n| `composition` | Complex utilities | @utility directives |\n| `keyframes` | Animation keyframes | @keyframes rules |\n| `transition` | Transitions | CSS custom properties |\n| `number` | Numeric values | CSS custom properties |\n\n## 🔄 Build Process\n\n### Development Workflow\n\n1. **Edit tokens**: Modify JSON files in `tokens/`\n2. **Build**: Run `npm run build-tokens`\n3. **Preview**: Use `npm run dev` to see changes\n4. **Type check**: Run `npm run type-check`\n\n### Production Build\n\n```bash\n# Complete build\nnpm run build\n\n# Output files:\n# dist/design-system.css - Main CSS output\n# demo/global.css - Demo CSS\n# dist/ - Compiled TypeScript\n```\n\n## 🎨 Generated CSS Structure\n\n```css\n@import 'tailwindcss';\n\n/* Custom variants */\n@custom-variant focus-visible (\u0026:focus-visible);\n\n/* Theme variables */\n@theme {\n  --color-brand-primary: oklch(0.570 0.191 248.32);\n  --spacing-4: 1rem;\n}\n\n/* Theme variants */\n@layer base {\n  [data-theme=\"dark\"] {\n    --color-theme-background: #000000;\n  }\n}\n\n/* Components */\n@layer components {\n  .c-button-primary {\n    background-color: var(--color-brand-primary);\n  }\n}\n\n/* Utilities */\n@utility flex-center {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n}\n```\n\n## 🚀 Examples\n\n### Theme Switching\n\n```html\n\u003c!-- Light theme (default) --\u003e\n\u003cbody\u003e\n  \u003cdiv class=\"bg-theme-background text-theme-content\"\u003e\n    Light theme content\n  \u003c/div\u003e\n\u003c/body\u003e\n\n\u003c!-- Dark theme --\u003e\n\u003cbody data-theme=\"dark\"\u003e\n  \u003cdiv class=\"bg-theme-background text-theme-content\"\u003e\n    Dark theme content\n  \u003c/div\u003e\n\u003c/body\u003e\n```\n\n### Component Usage\n\n```html\n\u003c!-- Using generated component classes --\u003e\n\u003cbutton class=\"c-button-primary\"\u003ePrimary Button\u003c/button\u003e\n\u003cbutton class=\"c-button-secondary\"\u003eSecondary Button\u003c/button\u003e\n\n\u003c!-- Using utility classes --\u003e\n\u003cdiv class=\"flex-center glass\"\u003eCentered glass effect\u003c/div\u003e\n```\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n1. **TypeScript errors**: Run `npm run type-check` to identify issues\n2. **Build failures**: Ensure all JSON files are valid\n3. **Missing tokens**: Check file paths and token references\n4. **CSS not updating**: Run full rebuild with `npm run build`\n\n### Debug Mode\n\nEnable verbose logging:\n\n```bash\nnpm run build-tokens -- --verbose\n```\n\n## 📚 Advanced Topics\n\n### Custom Transforms\n\nDefine custom Style Dictionary transforms:\n\n```typescript\nexport const customTransform = {\n  name: 'custom/transform',\n  type: 'value',\n  matcher: (token: Token) =\u003e token.$type === 'custom',\n  transform: (token: Token) =\u003e {\n    // Transform logic\n    return transformedValue;\n  }\n};\n```\n\n### Plugin Extensions\n\nExtend the base plugin with custom processors:\n\n```typescript\nimport { TokenProcessingEngine } from './config/token-engine.js';\nimport { CustomProcessor } from './custom-processor.js';\n\nconst engine = new TokenProcessingEngine(config);\nengine.registerProcessor('custom', new CustomProcessor());\n```\n\n## 🎯 Key Differences \u0026 Unconventional Patterns\n\n### 1. The `_` Default Pattern\n\n**Unlike standard approaches**, this tool uses `_` as the key for default/base theme values:\n\n```json\n{\n  \"color\": {\n    \"theme\": {\n      \"background\": {\n        \"_\": { \"$type\": \"color\", \"$value\": \"#fff\" },    // ← Default value\n        \"dark\": { \"$type\": \"color\", \"$value\": \"#000\" }  // ← Theme variant\n      }\n    }\n  }\n}\n```\n\n**Why?** This allows any token type to have theme variants, not just colors.\n\n### 2. CamelCase in JSON, Kebab-case in CSS\n\n**Token files use camelCase**, but **CSS output uses kebab-case**:\n\n```json\n{\n  \"backgroundColor\": \"blue\",\n  \"alignItems\": \"center\"\n}\n```\n\n**Becomes:**\n```css\nbackground-color: blue;\nalign-items: center;\n```\n\n### 3. Component Pseudo-selectors\n\n**Pseudo-selectors use `\u0026` prefix** in component tokens:\n\n```json\n{\n  \"$value\": {\n    \"color\": \"blue\",\n    \"\u0026:hover\": { \"color\": \"red\" },\n    \"\u0026:focus\": { \"outline\": \"2px solid blue\" }\n  }\n}\n```\n\n### 4. Token References vs CSS Variables\n\n**Use token references `{path.to.token}`**, not CSS variables:\n\n```json\n// ✅ Correct\n{\n  \"padding\": \"{spacing.4} {spacing.6}\",\n  \"color\": \"{color.brand.primary}\"\n}\n\n// ❌ Incorrect  \n{\n  \"padding\": \"var(--spacing-4) var(--spacing-6)\",\n  \"color\": \"var(--color-brand-primary)\"\n}\n```\n\n### 5. Multi-Type Theme Support\n\n**Any token type can have themes**, not just colors:\n\n```json\n{\n  \"spacing\": {\n    \"theme\": {\n      \"gap\": {\n        \"_\": { \"$type\": \"dimension\", \"$value\": \"1rem\" },\n        \"compact\": { \"$type\": \"dimension\", \"$value\": \"0.5rem\" }\n      }\n    }\n  }\n}\n```\n\n### 6. Composition vs Utility Types\n\n- **`utility`**: Basic utility class generation\n- **`composition`**: Enhanced processing with additional features\n\nBoth create `@utility` directives but with different processing pipelines.\n\n## 📄 License\n\nISC License - Feel free to use in your projects!\n\n---\n\n**Built with ❤️ using TypeScript, Style Dictionary, and Tailwind CSS v4**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokens-studio%2Fsd-tailwindv4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftokens-studio%2Fsd-tailwindv4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokens-studio%2Fsd-tailwindv4/lists"}