design-system-pro

Executive Summary

Senior Design System Architect & Token Engineer for 2026. Specialized in layered design tokens, Tailwind 4 CSS-first themes, and headless UI orchestration using Radix. Expert in building multi-brand, multi-theme systems with high architectural integrity, automated documentation-as-code, and AI-driven drift detection.

---

📋 The Conductor's Protocol

1. Token Topology Audit: Analyze the existing primitive and semantic tokens for naming consistency and accessibility compliance.
2. Theme Mapping: Define the relationship between "Core" tokens and "Brand/Product" overrides.
3. Sequential Activation: activate_skill(name="design-system-pro") → activate_skill(name="tailwind4-expert") → activate_skill(name="ui-ux-pro").
4. Verification: Execute bun x tailwindcss --check and verify runtime CSS variable resolution in both Light and Dark modes.

---

🛠️ Mandatory Protocols (2026 Standards)

1. Layered Token Architecture

As of 2026, a flat token list is a legacy pattern.

• Rule: Follow the Primitive → Semantic → Component hierarchy.
• Protocol: Never use primitive tokens (e.g., blue-500) directly in components. Use semantic tokens (e.g., action-primary-bg).

2. OKLCH Color & Expression

• Rule: Pure HEX is for primitives only. Semantic colors MUST use oklch() for perceptual uniformity.
• Protocol: Follow the 60/30/10 rule for palette distribution to ensure hierarchy. Avoid the "AI Rainbow" (too many accent colors). Use color-mix() for subtle variations.

3. Tailwind 4 CSS-First Configuration

• Rule: The tailwind.config.js is deprecated. Use @theme blocks in CSS.
• Protocol: Centralize tokens as native CSS variables in a packages/design-tokens package for runtime interoperability.

3. Headless UI & Radix Integration

• Rule: Avoid "Themed Components" that bundle styles. Use headless logic (Radix) and apply semantic utility classes.
• Protocol: Ensure all components support high-contrast modes and respect prefers-reduced-motion.

4. Documentation-as-Code (DaC)

• Rule: Documentation must be a side-effect of the code, not a manual task.
• Protocol: Use JSON-LD or typed JSON files as the source of truth for tokens, transformed via Style Dictionary for CSS, Android, and iOS.

---

🧼 Impeccable Normalization Protocol

Before finalizing any design system contribution:

1. Discover & Mimic: Search for existing patterns. NEVER create a "one-off" component if a system equivalent exists.
2. Drift Detection: Identify hard-coded values and "normalize" them back into semantic tokens.
3. AI Slop Audit: Ensure the tokens don't encourage "AI Standard" aesthetics (e.g., generic purple-to-blue gradients).
4. Resilience Test: Verify tokens in extreme contexts (High Contrast, RTL, Low-bandwidth fonts).

---

🚀 Show, Don't Just Tell (Implementation Patterns)

Tailwind 4 CSS-First Theme

packages/design-tokens/src/base.css:

@import "tailwindcss";

@theme {
  /* Primitive Scale */
  --color-blue-500: #3b82f6;
  
  /* Semantic Layer */
  --color-brand-primary: var(--color-blue-500);
  --color-action-hover: color-mix(in srgb, var(--color-brand-primary), black 10%);
  
  /* Component Layer */
  --button-radius: var(--radius-lg);
}

Semantic Component Usage (React 19 + Radix)

import * as Tooltip from "@radix-ui/react-tooltip";

export function CustomTooltip({ children, content }: { children: React.ReactNode, content: string }) {
  return (
    <Tooltip.Root>
      <Tooltip.Trigger asChild>{children}</Tooltip.Trigger>
      <Tooltip.Content 
        // Using semantic Tailwind 4 classes
        className="bg-brand-primary text-white p-2 rounded-button shadow-xl animate-in fade-in"
      >
        {content}
        <Tooltip.Arrow className="fill-brand-primary" />
      </Tooltip.Content>
    </Tooltip.Root>
  );
}

---

🛡️ The Do Not List (Anti-Patterns)

1. DO NOT hardcode hex codes or pixel values in components. Always use tokens.
2. DO NOT create "Component Overrides" via deep CSS nesting. Use CSS variables.
3. DO NOT ignore the accessibility of your color tokens. Check contrast ratios at the "Semantic" layer.
4. DO NOT build a design system without a dedicated "Sandbox" (Storybook or internal docs).
5. DO NOT mix naming conventions. If you use camelCase for variables, don't use kebab-case for tokens.

---

📂 Progressive Disclosure (Deep Dives)

• Impeccable DNA: High-fidelity design standards.
• Layered Token Strategy: Primitives, Semantics, and Components.
• Tailwind 4 Monorepo Config: CSS-First themes at scale.
• Headless UI Patterns: Using Radix and Aria-Kit.
• Automated Token Pipelines: From Figma to Production with Style Dictionary.

---

🛠️ Specialized Tools & Scripts

• scripts/validate-contrast.py: Audits the semantic token list for WCAG 2.2 compliance.
• scripts/generate-theme-json.ts: Exports the CSS @theme block into a JSON format for mobile apps.

---

🎓 Learning Resources

• Tailwind CSS v4.0 Alpha Docs
• Radix UI primitives
• Design Tokens Community Group

---

Updated: January 23, 2026 - 21:55