1  # F011-design_packages.component.cspec
  2  
  3  metadata:
  4    id: F011
  5    name: design_packages
  6    version: 1.0.0
  7    domain: frontend
  8    stability: stable
  9    updated: 2026-01-19
 10    cascade_priority: 4
 11    roles:
 12      primary: [Dev, Design]
 13      review: [Frontend]
 14    expertise:
 15      required: [design_systems, eslint, npm_publishing]
 16      helpful: [style_dictionary, tailwind, accessibility]
 17    context_tags: [design, tokens, eslint, brand, monorepo]
 18  
 19  dependencies:
 20    upstream: [F008]
 21    downstream: [F002, F003, F004, F006, F007]
 22  
 23  interface:
 24    types_ref: _registry/types.cspec
 25    types:
 26      package_scope: "@aspect"
 27      token_format: enum[css, js, json, tailwind]
 28      eslint_severity: enum[warn, error]
 29  
 30  spec:
 31    # === PURPOSE ===
 32    purpose: Centralized brand enforcement through distributable packages
 33  
 34    # === REPOSITORY STRUCTURE ===
 35    structure:
 36      acdc-design/:
 37        description: "Turborepo monorepo hosting all design packages"
 38        packages/:
 39          tokens/:
 40            package: "@aspect/design-tokens"
 41            description: "Design token distribution (CSS, JS, Tailwind)"
 42            build_tool: style_dictionary
 43            outputs:
 44              - css/variables.css
 45              - css/light.css
 46              - css/dark.css
 47              - js/index.js
 48              - js/index.d.ts
 49              - tailwind/preset.js
 50              - json/tokens.json
 51  
 52          eslint-plugin/:
 53            package: "@aspect/eslint-plugin-design"
 54            description: "ESLint rules enforcing token usage"
 55            rules:
 56              no-hardcoded-colors: error
 57              no-hardcoded-spacing: error
 58            configs:
 59              - recommended    # warnings - migration mode
 60              - strict         # errors - enforcement mode
 61  
 62          assets/:
 63            package: "@aspect/brand-assets"
 64            description: "Logo components and curated icons"
 65            logos:
 66              - AlphaLogo
 67              - DeltaLogo
 68              - CombinedLogo
 69            icon_source: lucide-react
 70  
 71        turbo.json: turborepo_config
 72        package.json: workspace_root
 73  
 74    # === PACKAGE EXPORTS ===
 75    tokens_exports:
 76      ".":
 77        import: "./dist/js/index.js"
 78        types: "./dist/js/index.d.ts"
 79        description: "Token constants with TypeScript types"
 80      "./css":
 81        import: "./dist/css/variables.css"
 82        description: "CSS custom properties (:root)"
 83      "./css/light":
 84        import: "./dist/css/light.css"
 85        description: "Light theme overrides"
 86      "./css/dark":
 87        import: "./dist/css/dark.css"
 88        description: "Dark theme overrides"
 89      "./tailwind":
 90        import: "./dist/tailwind/preset.js"
 91        description: "Tailwind preset with tokens"
 92      "./json":
 93        import: "./dist/json/tokens.json"
 94        description: "Raw token data"
 95  
 96    # === ESLINT PLUGIN EXPORTS ===
 97    eslint_exports:
 98      ".":
 99        rules:
100          - "@aspect/design/no-hardcoded-colors"
101          - "@aspect/design/no-hardcoded-spacing"
102        configs:
103          - "@aspect/design/recommended"
104          - "@aspect/design/strict"
105  
106    # === ASSET EXPORTS ===
107    asset_exports:
108      logos:
109        - "AlphaLogo"
110        - "DeltaLogo"
111        - "CombinedLogo"
112      icons:
113        - semantic_icons_reexported_from_lucide
114  
115    # === VERSION STRATEGY ===
116    versioning:
117      strategy: independent
118      tokens: semver_with_visual_regression
119      eslint_plugin: semver_standard
120      assets: semver_with_visual_regression
121      breaking_changes:
122        - removing_token
123        - renaming_token
124        - changing_token_value_significantly
125      minor_changes:
126        - adding_new_token
127        - adjusting_value_within_palette
128      patch_changes:
129        - documentation_updates
130        - build_improvements
131  
132    # === CI REQUIREMENTS ===
133    ci:
134      acdc_design:
135        jobs:
136          - validate-tokens          # JSON schema validation
137          - build-tokens             # Style Dictionary build
138          - contrast-check           # WCAG AA compliance
139          - eslint-plugin-test       # Rule unit tests
140          - brand-assets-build       # SVGO optimize, React build
141          - integration-test         # Consumer smoke test
142          - publish                  # npm publish on main
143  
144      consumer_apps:
145        required_job: lint-design-tokens
146        blocking: true
147        failure_action: pr_cannot_merge
148  
149    # === CONSUMER CONFIGURATION ===
150    consumer_setup:
151      install: |
152        yarn add @aspect/design-tokens @aspect/eslint-plugin-design @aspect/brand-assets
153  
154      eslint_config: |
155        // eslint.config.js (flat config)
156        import aspectDesign from '@aspect/eslint-plugin-design'
157  
158        export default [
159          aspectDesign.configs.strict,
160          // ... other configs
161        ]
162  
163      tailwind_config: |
164        // tailwind.config.ts
165        import aspectPreset from '@aspect/design-tokens/tailwind'
166  
167        export default {
168          presets: [aspectPreset],
169          // ... project config
170        }
171  
172      css_import: |
173        /* main.css */
174        @import '@aspect/design-tokens/css';
175        @import '@aspect/design-tokens/css/dark'; /* or light */
176  
177    # === MIGRATION PHASES ===
178    migration:
179      phase_1_audit:
180        duration: "Week 1"
181        actions:
182          - install_eslint_plugin_with_recommended_config
183          - generate_violation_report
184          - categorize_by_severity
185        expected_outcome: "Baseline violation count"
186  
187      phase_2_autofix:
188        duration: "Week 2"
189        actions:
190          - run_eslint_fix_on_codebase
191          - manually_address_unfixable_violations
192          - review_token_mapping_accuracy
193        expected_outcome: "90%+ violations resolved"
194  
195      phase_3_enforce:
196        duration: "Week 3"
197        actions:
198          - upgrade_to_strict_config
199          - enable_ci_blocking
200          - document_remaining_exceptions
201        expected_outcome: "CI enforcement active"
202  
203    # === PACKAGE REGISTRY ===
204    registry:
205      type: internal
206      url: "npm.ac-dc.network"
207      scope: "@aspect"
208      publish_trigger: main_branch_merge
209      access: organization_read
210  
211  implementation_plans:
212    - _plans/frontend/design-tokens-package.cspec
213    - _plans/frontend/eslint-plugin-package.cspec
214    - _plans/frontend/brand-assets-package.cspec
215    - _plans/frontend/design-integration-guide.cspec
216  
217  changelog:
218    - version: 1.0.0
219      date: 2026-01-19
220      type: initial
221      description: "Initial design packages spec for centralized brand enforcement"
222      breaking: false