# Design System Skill

A framework-agnostic design philosophy for building fluid, responsive interfaces. Works with any stack: React, Vue, Astro, Svelte, plain HTML/CSS, Tailwind, SCSS, or vanilla CSS.

## What This Is

This is a **thinking framework** for layout and design systems — not just code patterns. It teaches you to ask the right questions before writing CSS, generate mathematically-sound fluid scales, and build adaptive components that work on any background.

## Features

- **Fluid Typography** — Generate type scales using CSS `clamp()` with proper math
- **Fluid Spacing** — Spacing scales with 1-up and 2-up pairs (`size-md-lg`, `size-md-xl`)
- **Layout Philosophy** — When to use Grid vs Flex, grid areas, asymmetric layouts
- **Adaptive Colors** — Transparency-based tokens that work on any background
- **Hard Rules** — Opinionated defaults (icons always 1:1, logical properties everywhere)
- **Framework Agnostic** — Equal coverage for SCSS and Tailwind, works anywhere

## Quick Start

### For Claude Code Users

Copy the skill to your project:

```bash
# Copy to your .claude/skills directory
cp -r skills/flex-grid-flow ~/.claude/skills/

# Or copy to project-level
cp -r skills/flex-grid-flow your-project/.claude/skills/
```

### For Other AI Tools

Copy `skills/flex-grid-flow/SKILL.md` to your AI assistant's context or system prompt.

## What's Included

```
design-system-skill/
├── skills/
│   └── flex-grid-flow/
│       └── SKILL.md          # The main skill (design philosophy + patterns)
├── agents/
│   └── design-system-architect.md   # Interactive setup agent
└── examples/
    ├── _functions.scss       # SCSS fluid scale generators
    ├── tailwind-theme.css    # Tailwind v4 @theme config
    └── theme.html            # Visual preview template
```

## The Philosophy

### 1. Think Before You Code

Before writing any CSS, ask:
- What's the content hierarchy?
- What information is critical on small screens?
- Does this layout even need to change?

### 2. Fluid is Optional

Not everything needs to be fluid. Choose what makes sense:

| Option | Typography | Spacing |
|--------|------------|---------|
| Fluid both | Scales with viewport | Scales with viewport |
| Fluid type only | Scales with viewport | Fixed values |
| Fluid space only | Fixed values | Scales with viewport |
| Fixed both | Breakpoint-based | Breakpoint-based |

### 3. Mobile Doesn't Mean "Center Everything"

- Left-aligned content often scans better
- Asymmetric margins create visual interest
- Horizontal scroll (reel pattern) sometimes beats stacking
- Navigation varies: bottom bar, hamburger, tabs — context matters

### 4. Hard Rules

These are non-negotiable:

```css
/* Icons MUST be in a 1:1 container */
.icon {
  display: grid;
  place-items: center;
  aspect-ratio: 1;
}

/* Always use logical properties */
.element {
  padding-block: var(--size-md);    /* not padding-top/bottom */
  padding-inline: var(--size-lg);   /* not padding-left/right */
  margin-block-start: var(--size-sm); /* not margin-top */
}
```

## Fluid Type Scale Math

The formula for fluid values using CSS `clamp()`:

```
clamp(min, preferred, max)

Where preferred = slope × 100vw + intercept

slope = (maxSize - minSize) / (maxViewport - minViewport)
intercept = minSize - (slope × minViewport)
```

### Type Scale Ratios

| Ratio | Name | Feel |
|-------|------|------|
| 1.067 | Minor Second | Very tight |
| 1.125 | Major Second | Tight |
| 1.200 | Minor Third | Comfortable |
| 1.250 | Major Third | Relaxed |
| 1.333 | Perfect Fourth | Spacious |
| 1.414 | Augmented Fourth | Dramatic |
| 1.500 | Perfect Fifth | Very dramatic |
| 1.618 | Golden Ratio | Classical |

### Generate a Step

```
fontSize = baseSize × ratio^step

Example (Major Third, step 2):
fontSize = 16px × 1.25^2 = 25px
```

## Spacing Scale with Pairs

Base scale uses t-shirt sizing:

```
size-3xs → size-2xs → size-xs → size-sm → size-md → size-lg → size-xl → size-2xl → size-3xl
```

### 1-Up Pairs (one step jump)

```css
--size-sm-md: clamp(var(--size-sm-min), ..., var(--size-md-max));
--size-md-lg: clamp(var(--size-md-min), ..., var(--size-lg-max));
--size-lg-xl: clamp(var(--size-lg-min), ..., var(--size-xl-max));
```

### 2-Up Pairs (two step jump)

```css
--size-sm-lg: clamp(var(--size-sm-min), ..., var(--size-lg-max));
--size-md-xl: clamp(var(--size-md-min), ..., var(--size-xl-max));
--size-lg-2xl: clamp(var(--size-lg-min), ..., var(--size-2xl-max));
```

## Adaptive Color Tokens

Use transparency so components work on any background:

```css
:root {
  /* Transparency scale */
  --alpha-50: 4%;
  --alpha-100: 8%;
  --alpha-200: 12%;
  --alpha-300: 16%;
  --alpha-400: 24%;
  --alpha-500: 32%;

  /* Surface tokens using currentColor */
  --surface-hover: color-mix(in srgb, currentColor var(--alpha-100), transparent);
  --surface-active: color-mix(in srgb, currentColor var(--alpha-200), transparent);
  --surface-selected: color-mix(in srgb, currentColor var(--alpha-300), transparent);
}

/* Works on any background */
.button:hover {
  background: var(--surface-hover);
}
```

## Layout Patterns

### Grid Areas (for explicit layouts)

```css
.layout {
  display: grid;
  grid-template-areas:
    "header header"
    "sidebar main"
    "footer footer";
  grid-template-columns: 250px 1fr;
  grid-template-rows: auto 1fr auto;
}

.header { grid-area: header; }
.sidebar { grid-area: sidebar; }
.main { grid-area: main; }
.footer { grid-area: footer; }
```

### Auto-fit Grid (for card grids)

```css
.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(18rem, 100%), 1fr));
  gap: var(--size-md);
}
```

### Stack (vertical flow)

```css
.stack {
  display: flex;
  flex-direction: column;
  gap: var(--size-sm);
}
```

### Cluster (horizontal wrap)

```css
.cluster {
  display: flex;
  flex-wrap: wrap;
  gap: var(--size-xs);
  align-items: center;
}
```

## The Agent

The `design-system-architect` agent provides interactive setup:

1. Asks questions about your preferences
2. Generates `theme.html` with previews:
   - Type scale visualization
   - Space scale visualization
   - Button variants (pick A, B, or C)
   - Input variants (pick A, B, or C)
3. Creates `design_master.md` storing your decisions
4. Enforces those decisions on subsequent runs

### Agent Rules

- **Never invents** — asks when uncertain
- **Checks `design_master.md`** before any styling work
- **Only deviates** if explicitly requested
- **Logs new decisions** back to the master file

## Installation

### Claude Code

```bash
# Clone the repo
git clone https://github.com/oerlellijk/design-system-skill.git

# Copy skill to your project
cp -r design-system-skill/skills/flex-grid-flow your-project/.claude/skills/

# Copy agent (optional)
cp design-system-skill/agents/design-system-architect.md your-project/.claude/agents/
```

### Manual Integration

Copy the contents of `SKILL.md` into your AI tool's system prompt or context window.

## Examples

The `examples/` folder contains ready-to-use files:

- **`_functions.scss`** — SCSS functions for generating fluid scales
- **`tailwind-theme.css`** — Tailwind v4 `@theme` configuration
- **`theme.html`** — Visual preview template for your design tokens

## Contributing

Contributions welcome. Please:

1. Keep it framework-agnostic
2. Maintain equal SCSS/Tailwind coverage
3. Focus on philosophy, not just patterns
4. Test examples before submitting

## License

MIT

---

**Built for humans who think before they code.**