design-system-skill-oerlellijk

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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.**

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:

# 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:

/* 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)

--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)

--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:

: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)

.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)

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

Stack (vertical flow)

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

Cluster (horizontal wrap)

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

The Agent

The design-system-architect agent provides interactive setup:

Asks questions about your preferences
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)
Creates design_master.md storing your decisions
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

# 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:

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

License

MIT

Built for humans who think before they code.