npm package: @flitzrrr/frontend-design-skills
Description: Opinionated web design skills from curated sources — one install, every major AI coding tool.
Author: flitzrrr
Latest version: 1.1.1

# Frontend Design Skills

[![npm version](https://img.shields.io/npm/v/@flitzrrr/frontend-design-skills?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@flitzrrr/frontend-design-skills)
[![Skills](https://img.shields.io/badge/skills-21-blue?style=flat-square)](skills-src/)
[![Domains](https://img.shields.io/badge/domains-19-green?style=flat-square)](spec/domains/)
[![Platforms](https://img.shields.io/badge/platforms-9-orange?style=flat-square)](bin/cli.js)
[![Sources](https://img.shields.io/badge/sources-12-purple?style=flat-square)](scripts/config.yaml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

**Opinionated web design skills** distilled from **curated sources**. One install, every major AI coding tool.

---

## Quick Start

```bash
npx @flitzrrr/frontend-design-skills install
```

Detects installed platforms and provisions skills for each. Target a single platform with:

```bash
npx @flitzrrr/frontend-design-skills install <platform>
```

Where `<platform>` is one of: `claude-code`, `cursor`, `windsurf`, `lovable`, `codex`, `copilot`, `antigravity`, `opencode`, `aider`.

<details>
<summary>Manual setup (git clone)</summary>

```bash
git clone git@github.com:flitzrrr/frontend-design-skills.git
cd frontend-design-skills

# Symlink into target platform(s):
ln -sf $(pwd)/skills-src/* ~/.copilot/skills/          # VS Code / GitHub Copilot
ln -sf $(pwd)/skills-src/* ~/.codex/skills/             # Codex
ln -sf $(pwd)/skills-src/* ~/.gemini/antigravity/skills/ # Antigravity
ln -sf $(pwd)/skills-src/* ~/.config/opencode/skills/   # OpenCode
```

</details>

<details>
<summary>All CLI commands</summary>

| Command | Description |
| --- | --- |
| `npx @flitzrrr/frontend-design-skills install` | Install for all detected platforms |
| `npx @flitzrrr/frontend-design-skills install <platform>` | Install for a single platform |
| `npx @flitzrrr/frontend-design-skills update` | Pull latest skills |
| `npx @flitzrrr/frontend-design-skills list` | List all available skills |

</details>

---

## Platform Support

| Platform | Discovery Mechanism | Install Method |
| --- | --- | --- |
| Claude Code | `CLAUDE.md` (project-level) | `npx @flitzrrr/frontend-design-skills install claude-code` |
| Cursor | `.cursorrules` (project-level) | `npx @flitzrrr/frontend-design-skills install cursor` |
| Windsurf | `.windsurfrules` (project-level) | `npx @flitzrrr/frontend-design-skills install windsurf` |
| Lovable | `.lovable` (project-level) | `npx @flitzrrr/frontend-design-skills install lovable` |
| VS Code (GitHub Copilot) | `.github/copilot-instructions.md` + `~/.copilot/skills/` | `npx @flitzrrr/frontend-design-skills install copilot` |
| Codex | `AGENTS.md` + `~/.codex/skills/` | `npx @flitzrrr/frontend-design-skills install codex` |
| Antigravity (Gemini) | `~/.gemini/antigravity/skills/` | `npx @flitzrrr/frontend-design-skills install antigravity` |
| OpenCode | `~/.config/opencode/skills/` | `npx @flitzrrr/frontend-design-skills install opencode` |
| Aider | `.aider/conventions.md` | `npx @flitzrrr/frontend-design-skills install aider` |
| Any agent | Read `skills-src/<name>/SKILL.md` directly | Manual |

---

## Skill Categories

| Category | Skills | Focus |
| --- | --- | --- |
| Meta | `webdesign-review` | Orchestrates all 20 domain skills for comprehensive design reviews |
| Core Design | `ui-design`, `ux-design` | Layout, grids, visual hierarchy, IA, interaction patterns |
| Detail | `web-typography`, `color-theory`, `accessibility` | Font pairing, 60-30-10 rule, WCAG, BFSG compliance |
| Implementation | `responsive-design`, `navigation-design`, `usability`, `images-media`, `branding-identity` | Mobile-first, menu patterns, forms, SVG, brand strategy |
| Strategy | `customer-journey`, `design-process`, `ai-design-workflow`, `landing-pages`, `website-audit` | Personas, briefing, AI workflow, conversion, relaunch |
| Trends & Patterns | `design-trends`, `ui-patterns`, `visual-direction`, `component-patterns`, `agent-ui-design` | Award-winning patterns, Mobbin, Dribbble/Behance, 21st.dev |

All skills follow the [Agent Skills spec](https://agentskills.io) format (YAML frontmatter + Markdown body).

---

## Sources

| Tier | Source | Pages | Focus |
| --- | --- | ---: | --- |
| 1 (deep) | [webdesign-journal.de](https://www.webdesign-journal.de/) | 30 | UI/UX, typography, color, accessibility, branding, AI |
| 1 (deep) | [21st.dev](https://21st.dev/) | 39 | Component patterns, Agents SDK, chat UI |
| 2 (awards) | [Awwwards](https://www.awwwards.com/) | ~200 | Award-winning sites + their content |
| 2 (awards) | [CSS Design Awards](https://www.cssdesignawards.com/) | 80 | Website of the Day winners |
| 2 (awards) | [CSS Winner](https://www.csswinner.com/) | 60 | Award winners |
| 3 (galleries) | [Godly](https://godly.website/) | 80 | Curated design gallery |
| 3 (galleries) | [SiteInspire](https://www.siteinspire.com/) | 80 | Design inspiration |
| 3 (galleries) | [Lapa.ninja](https://www.lapa.ninja/) | 80 | Landing page gallery |
| 3 (galleries) | [Land-book](https://land-book.com/) | 30 | Design gallery |
| 4 (community) | [Dribbble](https://dribbble.com/) | 25 | Trending shots |
| 4 (community) | [Behance](https://www.behance.net/) | 20 | Trending projects |
| 4 (community) | [Mobbin](https://mobbin.com/) | 6 | Real app UI patterns (public) |

**809 pages** across 12 sources, synthesized into a **19-domain Enterprise Design Specification** (3,409 lines).

---

## Architecture

```mermaid
graph LR
    subgraph Sources
        direction TB
        T1[Tier 1 — Deep]
        T2[Tier 2 — Awards]
        T3[Tier 3 — Galleries]
        T4[Tier 4 — Community]
    end

    subgraph Pipeline
        direction TB
        scrape[scrape.py]
        diff[diff-content.py]
        spec[19 Domain Specs]
        skills[SKILL.md x 21]
        build[build-skills.py]
    end

    subgraph Platforms
        direction TB
        claude[Claude Code]
        cursor[Cursor]
        windsurf[Windsurf]
        copilot[Copilot]
        codex[Codex]
        aider[Aider]
    end

    Sources --> scrape --> diff --> spec -->|AI Synthesis| skills --> build --> Platforms
```

### Evolution Pipeline

```mermaid
graph LR
    cron(Cron — Sundays 3am) --> scrape

    subgraph Scrape & Diff
        scrape[scrape.py<br/>Crawl 12 sources] --> manifest[(manifest.json)]
        manifest --> diff[diff-content.py<br/>Compare hashes]
    end

    subgraph Map & Synthesize
        diff --> cmap[(content-map.json)]
        cmap --> domains[spec/domains/*.md<br/>19 domain files]
        domains -->|AI synthesis| skills[skills-src/<br/>SKILL.md x 21]
    end

    subgraph Build & Ship
        skills --> builder[build-skills.py]
        builder --> out1[Claude Code]
        builder --> out2[Cursor]
        builder --> out3[Windsurf]
        builder --> out4[+ 6 more]
    end
```

---

## Directory Structure

```
frontend-design-skills/
  skills-src/               21 canonical skills (Agent Skills spec)
    _template/              Skill authoring template
    webdesign-review/       Meta-skill (orchestrates all domains)
    ui-design/              ...through to...
    agent-ui-design/        ...all 21 skill directories
  spec/                     Enterprise Design Specification
    design-spec.md          Master index (19 domains)
    domains/                Per-domain spec files (01-19)
    content-map.json        URL-to-domain mapping
  tools/                    Cross-tool adapter system
    adapters/               6 Python adapters + common.py
    FORMAT-SPECS.md         Output format reference
  scripts/                  Build and automation
    build-skills.py         Canonical -> tool-specific outputs
    validate-skills.py      Agent Skills spec validation
    update-counts.js        Dynamic README badge management
    scrape.py               Tiered source scraper
    diff-content.py         Content change detection
    evolve.py               Evolution pipeline orchestrator
    config.yaml             Source configuration (12 sources, 4 tiers)
  data/                     Persistent scraping data
    manifest.json           URL/hash/date index
    changelog.md            Evolution log
    scraped/                Raw markdown (gitignored)
    versions/               Manifest snapshots for rollback
  bin/                      CLI (npx)
  output/                   Generated tool outputs (gitignored)
  docs/                     Project documentation
```

### Skill Format

Each skill follows the [Agent Skills](https://agentskills.io) specification:

```
skills-src/<name>/
  SKILL.md          < 500 lines, YAML frontmatter (name, description)
  references/       Detailed patterns, code examples, checklists
```

The build pipeline transforms this canonical format into tool-specific outputs via 6 adapters (Claude Code copies directly; Cursor generates `.mdc`; Windsurf/Gemini/Codex/Aider concatenate into single files with inlined references).

### Naming Convention

Skills are named by domain: `ui-design`, `web-typography`, `accessibility`. The meta-skill `webdesign-review` orchestrates all 20 domain skills for comprehensive design reviews.

---

## Validation

```bash
python3 scripts/validate-skills.py
```

Validates all 21 skills against the Agent Skills spec: frontmatter fields (`name`, `description`), naming conventions (lowercase-hyphen, max 64 chars), line limits (< 500), and directory-name consistency.

---

## License

MIT -- applies to all code, skills, and documentation in this repository.