AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

ui-design-system

Use when building a design system: tokens, component docs, responsive scales or developer handoff. Generates tokens with design_token_generator.py.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--ui-design-system at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 6

references/token-generation.md

Design Token Generation Guide

Reference for color palette algorithms, typography scales, and WCAG accessibility checking.


Table of Contents


Color Palette Generation

HSV Color Space Algorithm

The token generator uses HSV (Hue, Saturation, Value) color space for precise control.

┌─────────────────────────────────────────────────────────────┐
│                    COLOR SCALE GENERATION                   │
├─────────────────────────────────────────────────────────────┤
│  Input: Brand Color (#0066CC)                               │
│  ↓                                                          │
│  Convert: Hex → RGB → HSV                                   │
│  ↓                                                          │
│  For each step (50, 100, 200... 900):                      │
│    • Adjust Value (brightness)                              │
│    • Adjust Saturation                                      │
│    • Keep Hue constant                                      │
│  ↓                                                          │
│  Output: 10-step color scale                                │
└─────────────────────────────────────────────────────────────┘

Brightness Algorithm

# For light shades (50-400): High fixed brightness
if step < 500:
    new_value = 0.95  # 95% brightness

# For dark shades (500-900): Exponential decrease
else:
    new_value = base_value * (1 - (step - 500) / 500)
    # At step 900: brightness ≈ base_value * 0.2

Saturation Scaling

# Saturation increases with step number
# 50 = 30% of base saturation
# 900 = 100% of base saturation
new_saturation = base_saturation * (0.3 + 0.7 * (step / 900))

Complementary Color Generation

Brand Color: #0066CC (H=210°, S=100%, V=80%)
                    ↓
           Add 180° to Hue
                    ↓
Secondary: #CC6600 (H=30°, S=100%, V=80%)

Color Scale Output

| Step | Use Case | Brightness | Saturation | |------|----------|------------|------------| | 50 | Subtle backgrounds | 95% (fixed) | 30% | | 100 | Light backgrounds | 95% (fixed) | 38% | | 200 | Hover states | 95% (fixed) | 46% | | 300 | Borders | 95% (fixed) | 54% | | 400 | Disabled states | 95% (fixed) | 62% | | 500 | Base color | Original | 70% | | 600 | Hover (dark) | Original × 0.8 | 78% | | 700 | Active states | Original × 0.6 | 86% | | 800 | Text | Original × 0.4 | 94% | | 900 | Headings | Original × 0.2 | 100% |


Typography Scale System

Modular Scale (Major Third)

The generator uses a 1.25x ratio (major third) to create harmonious font sizes.

Base: 16px

Scale calculation:
  Smaller sizes: 16px ÷ 1.25^n
  Larger sizes: 16px × 1.25^n

Result:
  xs:   10px (16 ÷ 1.25²)
  sm:   13px (16 ÷ 1.25¹)
  base: 16px
  lg:   20px (16 × 1.25¹)
  xl:   25px (16 × 1.25²)
  2xl:  31px (16 × 1.25³)
  3xl:  39px (16 × 1.25⁴)
  4xl:  49px (16 × 1.25⁵)
  5xl:  61px (16 × 1.25⁶)

Type Scale Ratios

| Ratio | Name | Multiplier | Character | |-------|------|------------|-----------| | 1.067 | Minor Second | Tight | Compact UIs | | 1.125 | Major Second | Subtle | App interfaces | | 1.200 | Minor Third | Moderate | General use | | 1.250 | Major Third | Balanced | Default | | 1.333 | Perfect Fourth | Pronounced | Marketing | | 1.414 | Augmented Fourth | Bold | Editorial | | 1.618 | Golden Ratio | Dramatic | Headlines |

Pre-composed Text Styles

| Style | Size | Weight | Line Height | Letter Spacing | |-------|------|--------|-------------|----------------| | h1 | 48px | 700 | 1.2 | -0.02em | | h2 | 36px | 700 | 1.3 | -0.01em | | h3 | 28px | 600 | 1.4 | 0 | | h4 | 24px | 600 | 1.4 | 0 | | h5 | 20px | 600 | 1.5 | 0 | | h6 | 16px | 600 | 1.5 | 0.01em | | body | 16px | 400 | 1.5 | 0 | | small | 14px | 400 | 1.5 | 0 | | caption | 12px | 400 | 1.5 | 0.01em |


Spacing Grid System

8pt Grid Foundation

All spacing values are multiples of 8px for visual consistency.

Base Unit: 8px

Multipliers: 0, 0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 7, 8...

Results:
  0:  0px
  1:  4px  (0.5 × 8)
  2:  8px  (1 × 8)
  3:  12px (1.5 × 8)
  4:  16px (2 × 8)
  5:  20px (2.5 × 8)
  6:  24px (3 × 8)
  ...

Semantic Spacing Mapping

| Token | Numeric | Value | Use Case | |-------|---------|-------|----------| | xs | 1 | 4px | Inline icon margins | | sm | 2 | 8px | Button padding | | md | 4 | 16px | Card padding | | lg | 6 | 24px | Section spacing | | xl | 8 | 32px | Component gaps | | 2xl | 12 | 48px | Section margins | | 3xl | 16 | 64px | Page sections |

Why 8pt Grid?

  1. Divisibility: 8 divides evenly into common screen widths
  2. Consistency: Creates predictable vertical rhythm
  3. Accessibility: Touch targets naturally align to 48px (8 × 6)
  4. Integration: Most design tools default to 8px grids

Accessibility Contrast

WCAG Contrast Requirements

| Level | Normal Text | Large Text | Definition | |-------|-------------|------------|------------| | AA | 4.5:1 | 3:1 | Minimum requirement | | AAA | 7:1 | 4.5:1 | Enhanced accessibility |

Large text: ≥18pt regular or ≥14pt bold

Contrast Ratio Formula

Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)

Where:
  L1 = Relative luminance of lighter color
  L2 = Relative luminance of darker color

Relative Luminance:
  L = 0.2126 × R + 0.7152 × G + 0.0722 × B
  (Values linearized from sRGB)

Color Step Contrast Guide

| Background | Minimum Text Step | For AA | |------------|-------------------|--------| | 50 | 700+ | Large text at 600 | | 100 | 700+ | Large text at 600 | | 200 | 800+ | Large text at 700 | | 300 | 900 | - | | 500 (base) | White or 50 | - | | 700+ | White or 50-100 | - |

Semantic Colors Accessibility

Generated semantic colors include contrast colors:

{
  "success": {
    "base": "#10B981",
    "light": "#34D399",
    "dark": "#059669",
    "contrast": "#FFFFFF"  // For text on base
  }
}

Export Formats

JSON Format

Best for: Design tool plugins, JavaScript/TypeScript projects, APIs

{
  "colors": {
    "primary": {
      "50": "#E6F2FF",
      "500": "#0066CC",
      "900": "#002855"
    }
  },
  "typography": {
    "fontSize": {
      "base": "16px",
      "lg": "20px"
    }
  }
}

CSS Custom Properties

Best for: Web applications, CSS frameworks

:root {
  --colors-primary-50: #E6F2FF;
  --colors-primary-500: #0066CC;
  --colors-primary-900: #002855;
  --typography-fontSize-base: 16px;
  --typography-fontSize-lg: 20px;
}

SCSS Variables

Best for: SCSS/SASS projects, component libraries

$colors-primary-50: #E6F2FF;
$colors-primary-500: #0066CC;
$colors-primary-900: #002855;
$typography-fontSize-base: 16px;
$typography-fontSize-lg: 20px;

Format Selection Guide

| Format | When to Use | |--------|-------------| | JSON | Figma plugins, Storybook, JS/TS, design tool APIs | | CSS | Plain CSS projects, CSS-in-JS (some), web apps | | SCSS | SASS pipelines, component libraries, theming | | Summary | Quick verification, debugging |


Quick Reference

Generation Command

# Default (modern style, JSON output)
python scripts/design_token_generator.py "#0066CC"

# Classic style, CSS output
python scripts/design_token_generator.py "#8B4513" classic css

# Playful style, summary view
python scripts/design_token_generator.py "#FF6B6B" playful summary

Style Differences

| Aspect | Modern | Classic | Playful | |--------|--------|---------|---------| | Fonts | Inter, Fira Code | Helvetica, Courier | Poppins, Source Code Pro | | Border Radius | 8px default | 4px default | 16px default | | Shadows | Layered, subtle | Single layer | Soft, pronounced |


See also: component-architecture.md for component design patterns