diff --git a/.agents/skills/frontend-design/CHANGELOG.md b/.agents/skills/frontend-design/CHANGELOG.md new file mode 100644 index 0000000..4a41bfa --- /dev/null +++ b/.agents/skills/frontend-design/CHANGELOG.md @@ -0,0 +1,45 @@ +# Changelog + +All notable changes to this skill are documented here. Format follows [Keep a Changelog](https://keepachangelog.com). + +## [Unreleased] + +### Added +- `code-style.md` — quality rules for AI-generated code, anti-slop patterns for code, comment style guide +- `minimal-ui-patterns.md` — 5 new sub-styles (Sublime, Height, Pitch, Figma, Notion) +- `editorial-patterns.md` — 6 editorial sub-styles (Pentagram, Bloomberg BW, NYT Mag, It's Nice That, Apartamento, The Gentlewoman) +- `brutalist-patterns.md` — 5 brutalist sub-styles (Bandcamp, Working Format, Bloomberg BW covers, Brutalist Websites gallery, Slam Jam) +- `product-ui-patterns.md` — code-first deep-dive into 10 Linear-style product UI components +- Russian translations for `README.md` +- `layout.md` — container system, spacing scale, grids and asymmetric splits, composition patterns, responsive strategy (mobile-first, 480/768/1024) +- `accessibility.md` — semantics, keyboard contracts, focus design, forms, ARIA minimalism, announcements, 15-minute testing protocol +- `performance.md` — budgets (LCP/INP/CLS, page weight), font loading, images, CSS/JS restraint, third-party costs, measuring +- `imagery.md` — the no-stock decision tree, CSS/SVG art direction vocabulary, photo art direction, icon systems, favicon & og-image +- `examples/example-swiss.html` — Swiss-style museum exhibition site (zero JavaScript) + `assets/screenshot-swiss.svg` + +### Changed +- `SKILL.md` — added Agent Skills YAML frontmatter (`name`, `description`) for auto-discovery in Claude Code / claude.ai; process Steps 5–10 now reference `layout.md`, `accessibility.md`, `performance.md`, `imagery.md`; sub-skill table extended to 17 files; Quality Bar extended to 10 questions (accessibility + speed) +- `README.md` / `README.en.md` — accurate counts (18 files, 7,842 lines), new file table rows, Example 6, layout/a11y/perf steps, updated loading strategies +- Release notes (`release/`) — updated stale counts + +### Fixed +- Mixed-language title in `brutalist-patterns.md` (English heading now consistent) +- `README.md` no longer marks `README.en.md` as "in progress" — the English version is complete + + +## [1.0.0] — 2026-04-15 + +### Added +- `SKILL.md` — core principles, process, identity +- `aesthetics.md` — 7 high-level style directions +- `typography.md` — typefaces, scale, pairs, anti-patterns +- `color.md` — token system, palettes, contrast, dark mode +- `anti-patterns.md` — 28 AI-slop patterns with before/after +- `components.md` — buttons, forms, cards, navigation, states +- `motion.md` — animation, easing, accessibility +- `content.md` — headlines, body copy, CTAs, microcopy +- `checklist.md` — pre-ship QA +- `minimal-ui-patterns.md` — initial 6 sub-styles (Linear, Stripe, Vercel, Arc, Mercury, Cron) + +### Notes +First public release. 11 files, ~3,400 lines. Built from patterns observed across Linear, Stripe, Vercel, Arc, Pentagram, Müller-Brockmann, NYT Magazine, and others. diff --git a/.agents/skills/frontend-design/CONTRIBUTING.md b/.agents/skills/frontend-design/CONTRIBUTING.md new file mode 100644 index 0000000..f4315fb --- /dev/null +++ b/.agents/skills/frontend-design/CONTRIBUTING.md @@ -0,0 +1,84 @@ +# Contributing + +Thanks for considering a contribution. This skill lives from people who spot slop, document it, and ship better patterns. + +## What this repo is + +A collection of markdown files that teach AI agents how to build websites that read as designed, not generated. The files are designed to be **loadable independently** — agents can pull just what they need. + +## What we accept + +- **New anti-patterns** with before/after examples. If you saw an AI ship it, we want it documented. +- **Refinements to existing rules** that make them more specific or more actionable. +- **New sub-styles** in `aesthetics.md` or one of the `*-patterns.md` files — with real references, real palettes, real typography. +- **New components** in `product-ui-patterns.md` or `components.md` — with HTML, CSS, and all states. +- **New motion patterns** in `motion.md` — with timing, easing, accessibility considerations. +- **Translations.** The skill is currently English-first. Russian, Chinese, Spanish, Japanese are all welcome. + +## What we don't accept + +- Generic design advice ("use whitespace", "be consistent") without specifics. +- Patterns without references or concrete examples. +- Copy that could apply to any product ("empowering teams to thrive"). +- AI-slop patterns in the skill itself. If your PR introduces vague platitudes, it will be closed. + +## Style guide for contributions + +When writing for this repo, follow the same principles the repo teaches: + +- **Specific > general.** Numbers, names, dates, real references. +- **One accent > many neutrals.** Pick a pattern, commit to it. +- **Asymmetry > symmetry.** Don't center everything. +- **Restraint > decoration.** Every line must earn its place. + +## How to add an anti-pattern + +The best contributions are new anti-patterns. Format: + +```markdown +### [Number]. [Name of anti-pattern] + +**Slop signature:** What does the AI-shipped version look like? Be specific. + +**Why it's slop:** Why does this read as "AI generated"? + +**Replace with:** The specific replacement. Concrete values where possible. +``` + +See `anti-patterns.md` for 28 examples. + +## How to add a sub-style + +Sub-styles live in `minimal-ui-patterns.md`, `editorial-patterns.md`, or `brutalist-patterns.md`. Each must have: + +- **Live reference** (URL to a real product/studio that exemplifies it) +- **When to choose** (specific audience, project type) +- **Palette** (concrete hex tokens) +- **Typography** (specific typefaces, weights, sizes) +- **Layout patterns** (max-width, hero pattern, sidebar pattern) +- **Signature patterns** (what makes this sub-style recognizable) +- **Hallmarks** (what to preserve) +- **Anti-patterns** (what breaks the sub-style) + +## Pull request process + +1. Fork the repo. +2. Create a branch: `git checkout -b add-new-anti-pattern-x`. +3. Make your changes. +4. Run through `checklist.md` mentally for your own contribution. +5. Open a PR with a specific title: "Add: emoji-as-icon anti-pattern" not "Update docs". +6. Describe what you added and why. Link to real examples where possible. + +## Reporting issues + +Found an anti-pattern we missed? Open an issue with: + +- The pattern (what the AI shipped) +- A real example (link or screenshot if possible) +- Your proposed fix + +## Code of conduct + +- Be specific. "This is bad" is not feedback. "This violates the 8px grid system because the buttons use 7px padding" is. +- Reference real work. If you critique, cite. +- No marketing language. We're documenting slop to fight it, not adding to it. diff --git a/.agents/skills/frontend-design/LICENSE b/.agents/skills/frontend-design/LICENSE new file mode 100644 index 0000000..e721d46 --- /dev/null +++ b/.agents/skills/frontend-design/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Frontend Design Skill contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/.agents/skills/frontend-design/README.en.md b/.agents/skills/frontend-design/README.en.md new file mode 100644 index 0000000..2c17ab5 --- /dev/null +++ b/.agents/skills/frontend-design/README.en.md @@ -0,0 +1,541 @@ +# Frontend Design Skill + +> A modular skill for AI agents building websites and digital interfaces. Output that reads as if made by a senior designer at a top studio — not as if generated by an LLM guessing at "modern web design." + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Files](https://img.shields.io/badge/files-18-blue.svg)](#-whats-inside) +[![Lines](https://img.shields.io/badge/lines-7_842-blue.svg)](#-whats-inside) +[![Sub-styles](https://img.shields.io/badge/sub--styles-22-green.svg)](#-whats-inside) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) +[![No slop](https://img.shields.io/badge/no-purple--blue--gradient-purple.svg)](anti-patterns.md) + +**7,842 lines. 18 files. 22 sub-styles. Zero purple-to-blue gradients.** + +[Russian version →](README.md) + +--- + +## 📖 Contents + +- [The problem](#-the-problem) +- [The solution](#-the-solution) +- [Screenshot examples](#-screenshot-examples) +- [What's inside](#-whats-inside) +- [Quick start](#-quick-start) +- [Usage guide](#-usage-guide) +- [Loading strategies](#-loading-strategies) +- [Code quality](#-code-quality) +- [Who this is for](#-who-this-is-for) +- [Contributing](#-contributing) +- [License](#-license) + +--- + +## 🎯 The problem + +Ask any AI agent to build you a landing page. You will get: + +- 🔮 A purple-to-blue gradient hero +- 🎯 Centered headline, two CTA buttons, a "Trusted by 10,000+" logo bar +- 📦 Three identical feature cards in a row, repeated three times +- 🎠 A testimonial carousel with stock headshots +- 💬 Lorem-ipsum-level copy that says nothing + +This is **AI slop** — the visual shorthand for "an LLM made this." It is what every AI defaults to, because it is what every AI has seen ten thousand times in its training set. It is the gravitational center of generative output, and everything has to actively push against it. + +**The skills in this repo push against it.** + +--- + +## ✨ The solution + +``` +7,842 lines · 18 files · 22 sub-styles · 0 purple-to-blue gradients +``` + +| File | Lines | What's inside | +|---|---:|---| +| **[SKILL.md](SKILL.md)** | 212 | Core principles, process, identity. Agent Skills frontmatter | +| **[aesthetics.md](aesthetics.md)** | 320 | 7 high-level aesthetics | +| **[minimal-ui-patterns.md](minimal-ui-patterns.md)** | 924 | 11 SaaS sub-styles (Linear, Stripe, Vercel, ...) | +| **[editorial-patterns.md](editorial-patterns.md)** | 476 | 6 editorial sub-styles (Pentagram, NYT Mag, ...) | +| **[brutalist-patterns.md](brutalist-patterns.md)** | 437 | 5 brutalist sub-styles (Bandcamp, Working Format, ...) | +| **[product-ui-patterns.md](product-ui-patterns.md)** | 1434 | 10 Linear-style components with code | +| **[typography.md](typography.md)** | 351 | Typefaces, scale, pairs, anti-patterns | +| **[color.md](color.md)** | 303 | Tokens, palettes, contrast, dark mode | +| **[layout.md](layout.md)** | 295 | Containers, spacing scale, grids, responsive strategy | +| **[anti-patterns.md](anti-patterns.md)** | 376 | 28 AI-slop patterns with before/after | +| **[components.md](components.md)** | 420 | Buttons, forms, cards, states | +| **[motion.md](motion.md)** | 293 | Animation, easing, accessibility | +| **[content.md](content.md)** | 272 | Headlines, copy, microcopy | +| **[accessibility.md](accessibility.md)** | 269 | Semantics, keyboard, focus, ARIA, testing protocol | +| **[performance.md](performance.md)** | 210 | Budgets, fonts, images, Core Web Vitals | +| **[imagery.md](imagery.md)** | 226 | CSS/SVG compositions, photo direction, icons, favicon/og | +| **[code-style.md](code-style.md)** | 850 | Code quality, no GPT-slop, comments | +| **[checklist.md](checklist.md)** | 174 | Pre-ship QA | + +--- + +## 📸 Screenshot examples + +Six sites built using these skills — from warm typography to cold dark SaaS, Swiss grids, and raw brutalism. + +### Style previews (composition examples) + +The first two are design compositions demonstrating the styles: + +#### Example 1: Design studio *Halftone* (Editorial / Warm / Light) + +Built with `aesthetics.md` §2 (Editorial) + `editorial-patterns.md` (Pentagram archive). + +**What was applied from the skills:** +- Warm paper `#FAF6F0` + ink `#1A1714` + editorial red `#C8281C` (`color.md`) +- Fraunces display + Inter text + JetBrains Mono kickers (`typography.md`) +- Asymmetric hero, not centered-everything (`anti-patterns.md` §6) +- Hero headline `clamp(3.5rem, 9vw, 8.5rem)` — massive, not default (`typography.md`) +- 6 works as magazine index, not "3-card grid" (`anti-patterns.md` §12) +- Specific names: "Mira Almeida", "Q3 2026", "14,000 shelves" (`content.md`) +- No emoji, no stock photos (`anti-patterns.md` §10) +- Footer with colophon — real editorial pattern (`aesthetics.md` §2) + +![Halftone portfolio preview](assets/preview-halftone.svg) + +--- + +#### Example 2: SaaS product *Tempo* (Refined Minimal / Dark / Linear-style) + +Built with `minimal-ui-patterns.md` §1 (Linear). + +**What was applied from the skills:** +- Dark surface `#0A0A0A` + ink `#F5F5F5` + Linear purple `#7B85E6` (`color.md` §Dark Mode) +- **Not** pure black, **not** pure white — skill explicitly forbids (`color.md`) +- Accent purple slightly brightened for dark (`color.md`) +- Asymmetric hero: text left, dashboard right (`anti-patterns.md` §6) +- Hero headline makes a claim, not "Welcome to Tempo" (`content.md`) +- Dashboard mockup in CSS/SVG — no stock screenshots (`anti-patterns.md` §10) +- Real metrics: P95 latency, concrete commits with hash + impact (`content.md`) +- 3 asymmetric features: metrics / replay / install — three different formats (`anti-patterns.md` §11/12) +- Pricing: 2 honest tiers, not 3 with middle highlighted (`anti-patterns.md` §13) +- Footer with build info: `v2.4.7 · build a3f9c2 · uptime 99.98%` (`aesthetics.md` §6) + +![Tempo SaaS preview](assets/preview-tempo.svg) + +--- + +### Working examples (ready-made single-file sites) + +Four full sites in the [`examples/`](examples/) folder. Each is a single HTML file with inline CSS and minimal JS. Open in any browser — no build step. + +| # | Screenshot | File | Style | Skills applied | +|---|---|---|---|---| +| 1 | ![Magazine](assets/screenshot-magazine.svg) | [`example-magazine.html`](examples/example-magazine.html) | **Editorial** (NYT Magazine) | `editorial-patterns.md` + `typography.md` + `color.md` | +| 2 | ![SaaS](assets/screenshot-saas.svg) | [`example-saas.html`](examples/example-saas.html) | **Refined Minimal dark** (Linear) | `minimal-ui-patterns.md` + `product-ui-patterns.md` | +| 3 | ![Brutalist](assets/screenshot-brutalist.svg) | [`example-brutalist.html`](examples/example-brutalist.html) | **Brutalist** (Working Format) | `brutalist-patterns.md` + `typography.md` | +| 4 | ![Swiss](assets/screenshot-swiss.svg) | [`example-swiss.html`](examples/example-swiss.html) | **Swiss** (Müller-Brockmann) | `aesthetics.md` §3 + `layout.md` + `accessibility.md` | + +#### Example 3: Literary magazine *The Common Review* (Editorial) + +A quarterly journal of essays, criticism, and letters. Issue 14, Winter 2026, theme: "On Repair." + +**What was applied from the skills:** +- ✅ Source Serif 4 throughout (display + body — one family) (`typography.md`) +- ✅ JetBrains Mono for metadata (issue numbers, page numbers, dates) (`typography.md`) +- ✅ **B/W minimal** + editorial red `#C8281C` accent (`color.md`) +- ✅ Asymmetric hero with SVG cover-art "after Ruskin" (`anti-patterns.md` §10) +- ✅ **Drop cap** on the lede paragraph — true editorial pattern (`editorial-patterns.md` §3) +- ✅ Pull quote with rules above/below (`editorial-patterns.md` §3) +- ✅ Section markers (§01, §02, §03) with rules (`editorial-patterns.md` §1) +- ✅ Real-feeling content: "Marta Bellucci spent three months with one of the youngest, who is sixty-three" (`content.md`) +- ✅ Colophon in footer (`editorial-patterns.md` §1) + +--- + +#### Example 4: Feature flag system *Latch* (SaaS / Linear-style) + +Developer tool for product teams. Sub-style: Linear. + +**What was applied from the skills:** +- ✅ Dark surface `#0A0A0B` + ink `#F4F4F5` (NOT pure black/white — `color.md` explicitly forbids) +- ✅ Mint accent `#6EE7B7` — used <10% of pixels (`color.md` §"How to Use the Accent") +- ✅ Hero asymmetric: text left, dashboard right (`anti-patterns.md` §6) +- ✅ Hero headline: "Feature flags that don't get in the way." — specific claim (`content.md`) +- ✅ **Dashboard mockup in CSS-only**: panel chrome, segmented control, flag rows with toggle (`product-ui-patterns.md` §1, §6) +- ✅ 3 asymmetric features: install (with code block) / targeting (with viz) / speed (with viz) (`anti-patterns.md` §11/12) +- ✅ Pricing: 2 honest tiers (Hobby + Production) (`anti-patterns.md` §13) +- ✅ Footer with build info: `v3.2.7 · build 8f4a12 · uptime 99.99%` (`aesthetics.md` §6) +- ✅ Tabular numerals everywhere (font-variant-numeric) (`typography.md`) +- ✅ JavaScript: segmented control + interactive toggle (`components.md`) + +--- + +#### Example 5: Indie label *Constellation Records* (Brutalist) + +Independent record label from Montréal. Sub-style: Working Format + Bandcamp. + +**What was applied from the skills:** +- ✅ **Marquee** with announcements (60s loop, respects `prefers-reduced-motion`) (`motion.md`) +- ✅ Pure black `#0A0A0A` + warm cream `#F4F1EB` + electric red `#FF2400` (`brutalist-patterns.md` §2) +- ✅ **Sharp corners everywhere** (`border-radius: 0`) (`brutalist-patterns.md` §"Anti-patterns") +- ✅ Hero with massive display type, italic accent in red (`brutalist-patterns.md` §"Hallmarks") +- ✅ Hero meta column in inverted color (ink background, surface text) (`brutalist-patterns.md` §2) +- ✅ Album covers as **CSS-only abstract compositions** (concentric circles, squares) (`anti-patterns.md` §10) +- ✅ Catalog: 8 releases, hover shifts padding + title color (`components.md`) +- ✅ **Manifesto section** with large typography, italic emphasis in accent (`editorial-patterns.md` §1 + brutalist merge) +- ✅ Tour dates with status indicators (`ON SALE` / `SOLD OUT`) (`components.md` §"Status indicators") +- ✅ Footer in inverted color, markers in accent color (`brutalist-patterns.md` §2) + +--- + +#### Example 6: *Ordnung* exhibition at Haus der Form (Swiss) + +Museum exhibition of Swiss graphic design, 1950–1980. Sub-style: Müller-Brockmann / International Typographic. + +**What was applied from the skills:** +- ✅ **Zero JavaScript** — pure HTML + CSS (`performance.md` §"JavaScript — Ship None If You Can") +- ✅ One grotesque (Archivo) throughout + IBM Plex Mono for metadata (`aesthetics.md` §3, `typography.md`) +- ✅ Hero smaller than expected — `clamp(2.75rem, 6vw, 4.5rem)`, Swiss restraint (`aesthetics.md` §3) +- ✅ **Type as image**: giant "1950→1980" in tabular figures as the visual anchor (`typography.md` §Numerals) +- ✅ White / pure black / one red #D62828 — "surface: white or black, nothing in between" (`aesthetics.md` §3) +- ✅ Meta-column pattern (200px + 1fr) in every section (`layout.md` §"The meta-column pattern") +- ✅ No buttons; the table hover inverts — black background, white text, red catalog number (`layout.md`, `components.md`) +- ✅ A real catalogue: Müller-Brockmann "Beethoven" 1955, Neue Grafik issues 1–46, Ruder's "Typographie" 1967 (`content.md`) +- ✅ Skip link, semantic table with caption, `:focus-visible`, `prefers-reduced-motion` (`accessibility.md`) +- ✅ Map as a CSS grid artifact instead of a stock map embed (`imagery.md` §"The vocabulary") + +--- + +## 🚀 Quick start + +### 1. Clone + +```bash +git clone https://github.com/AkyRayy/Frontend-Design-SKILLS-for-AI.git +cd Frontend-Design-SKILLS-for-AI +``` + +### 2. Load into your agent's context + +Depends on the platform: + +| Platform | Where to put it | +|---|---| +| **Claude Code / Cursor** | `.claude/skills/frontend-design/` — `SKILL.md` carries Agent Skills frontmatter (`name` + `description`), so the skill is discovered automatically | +| **Continue** | `.continue/skills/frontend-design/` | +| **Cline / Roo Code** | `.roo/skills/frontend-design/` | +| **Custom agent** | Copy the relevant `.md` files into your system prompt | + +### 3. Use + +``` +[context: SKILL.md + aesthetics.md + minimal-ui-patterns.md] + +User: Build me a landing page for an observability SaaS. + +Agent: [reads SKILL.md, picks "Refined Minimal" → sub-style "Linear"] + [identifies the job of the page] + [builds the token system from color.md] + [sets typography from typography.md] + [avoids 28 patterns from anti-patterns.md] + [writes code in style from code-style.md] + → outputs a design that reads as a senior designer's work +``` + +--- + +## 📘 Usage guide + +### Step 0 — Before you start + +Read **[SKILL.md](SKILL.md)** end to end. It's the core. Everything else is detail. + +Remember three questions the agent should ask itself **at every step**: + +1. **What is the job of this page?** (one sentence) +2. **Which aesthetic am I in?** (one, not a mix) +3. **What should dominate?** (one element, not five) + +### Step 1 — Identify the job of the page + +Without this, everything else is slop. Ask yourself: **why did the user come here, and what should they do?** + +``` +❌ "Landing page for our SaaS" → unclear what to do +✅ "Convince a frontend engineer to try the product → get email signup" +✅ "Sell a $40 cookbook to design-minded home cooks" +✅ "Get a designer to apply to our 4-person studio" +``` + +Write one sentence. Every section must serve that job. + +### Step 2 — Pick the aesthetic + +Open **[aesthetics.md](aesthetics.md)**. Seven high-level aesthetics: + +| Aesthetic | When to pick | +|---|---| +| **Refined Minimal** | SaaS, fintech, dev tools, B2B | +| **Editorial / Magazine** | Publishing, premium content, manifestos | +| **Swiss / Typographic** | Galleries, museums, archives | +| **Brutalist / Raw** | Music, fashion, art, counterculture | +| **Soft / Hand-crafted** | Lifestyle, hospitality, indie SaaS | +| **Technical / Mono** | Dev tools, API, documentation | +| **Playful / Geometric** | Consumer, kids, gaming, creative | + +**Commit. Don't blend two.** + +### Step 3 — Drill into a sub-style + +Open the corresponding sub-style file: + +- **Refined Minimal** → [minimal-ui-patterns.md](minimal-ui-patterns.md) (11 sub-styles) +- **Editorial** → [editorial-patterns.md](editorial-patterns.md) (6 sub-styles) +- **Brutalist** → [brutalist-patterns.md](brutalist-patterns.md) (5 sub-styles) + +Pick a specific sub-style (Linear, Stripe, Vercel, NYT Magazine, Bandcamp, ...) and commit. Don't blend two. + +### Step 4 — Build the token system + +Open **[color.md](color.md)** and **[typography.md](typography.md)**. Set up: + +```css +:root { + /* Palette from color.md, specific hex */ + --surface: ... + --ink: ... + --accent: ... + + /* Typography from typography.md */ + --font-display: ... + --font-text: ... + --font-mono: ... + + /* Scale 1.25 or 1.333 */ + --text-base: 1rem; + --text-2xl: 1.953rem; + /* ... */ +} +``` + +**No raw hex in components.** All colors through tokens. + +### Step 4½ — Set the page skeleton + +Open **[layout.md](layout.md)**. Container (`1200–1280px`), spacing scale (`4/8/12/16/24/32/48/64/96/128`), asymmetric splits (`5/7`, `3/9` — not equal thirds), the meta-column pattern, breakpoints at `480/768/1024`. Grid and spacing are decided before the first component exists. + +### Step 5 — Avoid slop + +Open **[anti-patterns.md](anti-patterns.md)**. **28 specific patterns** to reject. Each with a "before" and "after" example. + +Before writing the next section, check: **am I repeating one of these 28?** + +### Step 6 — Build components right + +| What you're building | Where the rules are | +|---|---| +| Buttons, forms, navigation | [components.md](components.md) | +| Product chrome (sidebar, command palette) | [product-ui-patterns.md](product-ui-patterns.md) | +| Icons, images, favicon/og | [imagery.md](imagery.md) | +| Animations | [motion.md](motion.md) | + +**Every component needs 8 states:** default, hover, focus-visible, active, disabled, loading, empty, error. Without them, the design breaks on the edges. + +### Step 7 — Write specific content + +Open **[content.md](content.md)**. Main rules: + +| ❌ Slop | ✅ Specific | +|---|---| +| "Welcome to [Brand]" | "Design that doesn't need explaining." | +| "Empowering businesses to thrive" | "Ship features 3x faster" | +| "Trusted by 10,000+" | "Used by Linear, Vercel, Stripe" | +| "Lorem ipsum" | Real names, dates, numbers | + +### Step 8 — Write quality code + +Open **[code-style.md](code-style.md)**. This is the skill for code — no GPT-slop in comments, no bloated functions, no `any`, no magic numbers. + +**Main rule:** names are the design. Spend more time choosing a name than writing the line of code. + +### Step 8½ — Accessibility and speed + +Open **[accessibility.md](accessibility.md)** and **[performance.md](performance.md)**. + +- **A11y:** semantics, a keyboard pass, `:focus-visible`, ARIA minimalism, AA contrast — plus the 15-minute testing protocol before shipping. +- **Perf:** budgets (LCP < 2.5s, CLS < 0.1, ≤ 4 font files, zero blocking JS). An HTML+CSS page with no JS is the norm, not an achievement. + +### Step 9 — Run the checklist + +Open **[checklist.md](checklist.md)**. **70+ items** across typography, color, layout, components, motion, accessibility, edge cases. + +**Final tests:** + +1. Would Massimo Vignelli approve? +2. Could you ship this at Linear / Pentagram / NYT? +3. Would you screenshot this for design inspiration? +4. Would you be proud to put your name on this? + +If 6+ answers are "no" — keep iterating. + +--- + +## 🎯 Loading strategies + +### Minimum viable (fast, fewer tokens) + +``` +1. SKILL.md ← core +2. aesthetics.md ← pick aesthetic +3. checklist.md ← before shipping +``` + +### Standard load (recommended) + +``` +1. SKILL.md +2. aesthetics.md +3. typography.md +4. color.md +5. layout.md +6. checklist.md +``` + +### B2B SaaS (Linear / Stripe / Vercel) + +``` +1. SKILL.md +2. minimal-ui-patterns.md ← instead of aesthetics.md §1 +3. typography.md +4. color.md +5. layout.md +6. product-ui-patterns.md ← for sidebar, command palette, etc +7. accessibility.md ← interactive products raise the a11y bar +8. checklist.md +``` + +### Editorial (Pentagram / NYT Mag) + +``` +1. SKILL.md +2. editorial-patterns.md ← instead of aesthetics.md §2 +3. typography.md +4. color.md +5. layout.md +6. checklist.md +``` + +### Brutalist (Bandcamp / Working Format) + +``` +1. SKILL.md +2. brutalist-patterns.md ← instead of aesthetics.md §4 +3. typography.md +4. checklist.md +``` + +### Product / interactive app + +``` +1. SKILL.md +2. minimal-ui-patterns.md +3. typography.md + color.md + layout.md +4. product-ui-patterns.md ← chrome: sidebar, ⌘K, list items, modals +5. accessibility.md ← focus traps, ARIA, keyboard +6. performance.md ← INP/CLS under load +7. checklist.md +``` + +### Full load (deep work) + +All 18 files. Used when the project demands maximum specificity. + +--- + +## 💎 Code quality + +Beyond design, the repo includes **[code-style.md](code-style.md)** — a skill for the code that AI agents write. + +**Core principles:** + +| Principle | Anti-pattern | +|---|---| +| **Names are the design** | `processData`, `doSomething`, `result` — all broken | +| **Comments explain WHY, not WHAT** | `// This function adds two numbers` above `add(a, b)` | +| **Errors are values** | `catch (e) {}` silently swallows errors | +| **Small functions** | A 200-line function with 8 parameters | +| **No `any`** | TypeScript lying to itself | +| **Delete first** | Before adding code, ask: can I delete something? | + +**GPT-slop in code** (catalog of 30+ patterns): +- Comments like "This function does X" (the code already does that) +- Empty `catch {}` +- `any`, `as any`, `@ts-ignore` without justification +- Magic numbers (`0.5`, `3600`, `100`) without names +- Functions with boolean flags: `doThing(x, true, false)` +- Dependencies for a single function + +**Full catalog and rules** → [code-style.md](code-style.md) + +--- + +## 👥 Who this is for + +- **AI agent builders** — to raise the quality of frontend output +- **Designers using AI** — to stop fixing the same 5 patterns every time +- **Developers without a designer** — so AI-generated sites look considered, not generated +- **Founders shipping fast** — so they don't ship ugly + +**This is not for:** designers who already produce great work — you don't need it. It's for everyone downstream of an LLM who wants to upgrade the output. + +--- + +## 🚫 What this is NOT + +- **❌ Not a Figma plugin.** It's a markdown skill for AI agents, not a design tool for humans. +- **❌ Not a CSS framework.** It produces no code; it shapes the code the agent writes. +- **❌ Not a replacement for taste.** The skill raises the floor. The ceiling is still up to you. +- **❌ Not magic.** A skill is a set of instructions. If the agent doesn't follow them, the output is still slop. + +--- + +## 🤝 Contributing + +PRs welcome. Especially: + +- **New anti-patterns** with before/after examples (format in CONTRIBUTING.md) +- **New sub-styles** in `minimal-ui-patterns.md` / `editorial-patterns.md` / `brutalist-patterns.md` +- **New components** in `product-ui-patterns.md` (HTML + CSS + all states) +- **Translations** — repo is English-first currently, but Russian ([README.md](README.md)), Chinese, Spanish, Japanese all welcome + +**What we don't accept:** generic advice ("use whitespace"), patterns without examples, marketing language. + +Details: **[CONTRIBUTING.md](CONTRIBUTING.md)** + +--- + +## 📜 License + +**[MIT](LICENSE)** — use it, modify it, redistribute it. If you ship something good with it, that's the thanks. + +--- + +## 🙏 Credits + +Patterns observed in: + +**Product design:** Linear, Stripe, Vercel, Arc, Cron, Mercury, Pitch, Height, Figma, Notion, Sublime + +**Studio work:** Pentagram, &Walsh, DIA Studio, Manual, Working Format, Locomotive, Bureau Mirko Borsche, Studio Dumbar + +**Editorial:** NYT Magazine, Bloomberg Businessweek, It's Nice That, Wallpaper*, Apartamento, The Gentlewoman, Kinfolk + +**Swiss / International Typographic:** Müller-Brockmann, Massimo Vignelli, Jan Tschichold, Wim Crouwel, Erik Spiekermann + +**Type design:** Stefan Sagmeister, Paula Scher, Tibor Kalman, Michael Bierut + +If you recognize the patterns — that's the point. If you don't — read the references, then read the code. + +--- + +> **If the design is good, you won't notice the design. If it's bad, you notice immediately.** +> +> Your job is the first. Slop is the second. diff --git a/.agents/skills/frontend-design/README.md b/.agents/skills/frontend-design/README.md new file mode 100644 index 0000000..e414ae3 --- /dev/null +++ b/.agents/skills/frontend-design/README.md @@ -0,0 +1,541 @@ +# Frontend Design Skill + +> Модульный скилл для ИИ-агентов, создающих веб-сайты и интерфейсы. Результат, который читается как работа старшего дизайнера — не как вывод LLM. + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Files](https://img.shields.io/badge/files-18-blue.svg)](#-что-внутри) +[![Lines](https://img.shields.io/badge/lines-7_842-blue.svg)](#-что-внутри) +[![Sub-styles](https://img.shields.io/badge/sub--styles-22-green.svg)](#-что-внутри) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) +[![No slop](https://img.shields.io/badge/no-purple--blue--gradient-purple.svg)](anti-patterns.md) + +**7 842 строки. 18 файлов. Ноль фиолетово-синих градиентов.** + +[English version →](README.en.md) + +--- + +## 📖 Содержание + +- [Проблема](#-проблема) +- [Решение](#-решение) +- [Скриншоты примеров](#-скриншоты-примеров) +- [Что внутри](#-что-внутри) +- [Быстрый старт](#-быстрый-старт) +- [Гайд по использованию](#-гайд-по-использованию) +- [Стратегии загрузки](#-стратегии-загрузки) +- [Качество кода](#-качество-кода) +- [Кто это использует](#-кто-это-использует) +- [Contributing](#-contributing) +- [Лицензия](#-лицензия) + +--- + +## 🎯 Проблема + +Попросите любого ИИ-агента сделать лендинг. Вы получите: + +- 🔮 Hero-секцию с фиолетово-синим градиентом +- 🎯 Центрированный заголовок, две CTA-кнопки, лого-бар «Trusted by 10,000+» +- 📦 Три одинаковые карточки фич в ряд, повторённые три раза +- 🎠 Карусель отзывов со стоковыми фотографиями +- 💬 Lorem-ipsum-уровень копирайтинга, который ничего не говорит + +Это **AI slop** — визуальный маркер «это сгенерировано LLM». Это то, что выдаёт каждый ИИ по умолчанию, потому что это то, что каждый ИИ видел десять тысяч раз в обучающих данных. Это гравитационный центр генеративного вывода, и всё должно активно с ним бороться. + +**Скиллы в этом репозитории борются с ним.** + +--- + +## ✨ Решение + +``` +7 842 строки · 18 файлов · 22 подстиля · 0 фиолетово-синих градиентов +``` + +| Файл | Строк | Что внутри | +|---|---:|---| +| **[SKILL.md](SKILL.md)** | 212 | Ядро: принципы, процесс, идентичность. Agent Skills frontmatter | +| **[aesthetics.md](aesthetics.md)** | 320 | 7 высокоуровневых эстетик | +| **[minimal-ui-patterns.md](minimal-ui-patterns.md)** | 924 | 11 подстилей SaaS (Linear, Stripe, Vercel, ...) | +| **[editorial-patterns.md](editorial-patterns.md)** | 476 | 6 editorial подстилей (Pentagram, NYT Mag, ...) | +| **[brutalist-patterns.md](brutalist-patterns.md)** | 437 | 5 brutalist подстилей (Bandcamp, Working Format, ...) | +| **[product-ui-patterns.md](product-ui-patterns.md)** | 1434 | 10 компонентов Linear-style с кодом | +| **[typography.md](typography.md)** | 351 | Шрифты, шкала, пары, анти-паттерны | +| **[color.md](color.md)** | 303 | Токены, палитры, контраст, dark mode | +| **[layout.md](layout.md)** | 295 | Контейнеры, spacing-шкала, сетки, адаптивность | +| **[anti-patterns.md](anti-patterns.md)** | 376 | 28 AI-slop паттернов с до/после | +| **[components.md](components.md)** | 420 | Кнопки, формы, карточки, состояния | +| **[motion.md](motion.md)** | 293 | Анимация, easing, accessibility | +| **[content.md](content.md)** | 272 | Заголовки, копирайтинг, микрокопи | +| **[accessibility.md](accessibility.md)** | 269 | Семантика, клавиатура, фокус, ARIA, тест-протокол | +| **[performance.md](performance.md)** | 210 | Бюджеты, шрифты, картинки, Core Web Vitals | +| **[imagery.md](imagery.md)** | 226 | CSS/SVG-композиции, фото-арт-дирекшн, иконки, favicon/og | +| **[code-style.md](code-style.md)** | 850 | Качество кода, без GPT-slop, комментарии | +| **[checklist.md](checklist.md)** | 174 | Pre-ship QA | + +--- + +## 📸 Скриншоты примеров + +Шесть сайтов, построенных с применением этих скиллов — от тёплой типографики до холодного dark SaaS, швейцарской сетки и сырого брутализма. + +### Демонстрационные превью (стилевые композиции) + +Два первых — дизайн-композиции, демонстрирующие стили: + +#### Пример 1: Дизайн-студия *Halftone* (Editorial / Warm / Light) + +Создано с применением `aesthetics.md` §2 (Editorial) + `editorial-patterns.md` (Pentagram archive). + +**Что применено из скиллов:** +- Warm paper `#FAF6F0` + ink `#1A1714` + editorial red `#C8281C` (`color.md`) +- Fraunces display + Inter text + JetBrains Mono kickers (`typography.md`) +- Асимметричный hero, не centered-everything (`anti-patterns.md` §6) +- Hero headline `clamp(3.5rem, 9vw, 8.5rem)` — массивный, не дефолтный (`typography.md`) +- 6 работ как magazine index, не «3-card grid» (`anti-patterns.md` §12) +- Конкретные имена: «Mira Almeida», «Q3 2026», «14,000 shelves» (`content.md`) +- Никаких emoji, никаких стоковых фото (`anti-patterns.md` §10) +- Footer с colophon — реальный editorial паттерн (`aesthetics.md` §2) + +![Halftone portfolio preview](assets/preview-halftone.svg) + +--- + +#### Пример 2: SaaS-продукт *Tempo* (Refined Minimal / Dark / Linear-style) + +Создано с применением `minimal-ui-patterns.md` §1 (Linear). + +**Что применено из скиллов:** +- Dark surface `#0A0A0A` + ink `#F5F5F5` + Linear purple `#7B85E6` (`color.md` §Dark Mode) +- **Не** pure black, **не** pure white — скилл явно запрещает (`color.md`) +- Accent purple слегка светлее в dark mode (`color.md`) +- Асимметричный hero: текст слева, dashboard справа (`anti-patterns.md` §6) +- Hero headline делает claim, не «Welcome to Tempo» (`content.md`) +- Dashboard mockup в CSS/SVG — без стоковых скриншотов (`anti-patterns.md` §10) +- Реальные метрики: P95 latency, конкретные commits с hash + impact (`content.md`) +- 3 фичи asymmetric: metrics / replay / install — три разных формата (`anti-patterns.md` §11/12) +- Pricing: 2 честных tier'а, не 3 с middle highlighted (`anti-patterns.md` §13) +- Footer с build info: `v2.4.7 · build a3f9c2 · uptime 99.98%` (`aesthetics.md` §6) + +![Tempo SaaS preview](assets/preview-tempo.svg) + +--- + +### Рабочие примеры (готовые single-file сайты) + +Четыре полноценных сайта в папке [`examples/`](examples/). Каждый — single HTML файл с встроенным CSS и минимальным JS. Открывается в любом браузере без сборки. + +| # | Скриншот | Файл | Стиль | Применённые скиллы | +|---|---|---|---|---| +| 1 | ![Magazine](assets/screenshot-magazine.svg) | [`example-magazine.html`](examples/example-magazine.html) | **Editorial** (NYT Magazine) | `editorial-patterns.md` + `typography.md` + `color.md` | +| 2 | ![SaaS](assets/screenshot-saas.svg) | [`example-saas.html`](examples/example-saas.html) | **Refined Minimal dark** (Linear) | `minimal-ui-patterns.md` + `product-ui-patterns.md` | +| 3 | ![Brutalist](assets/screenshot-brutalist.svg) | [`example-brutalist.html`](examples/example-brutalist.html) | **Brutalist** (Working Format) | `brutalist-patterns.md` + `typography.md` | +| 4 | ![Swiss](assets/screenshot-swiss.svg) | [`example-swiss.html`](examples/example-swiss.html) | **Swiss** (Müller-Brockmann) | `aesthetics.md` §3 + `layout.md` + `accessibility.md` | + +#### Пример 3: Литературный журнал *The Common Review* (Editorial) + +Квартальный журнал эссе, критики и писем. Issue 14, Winter 2026, тема номера — «On Repair». + +**Что применено из скиллов:** +- ✅ Source Serif 4 throughout (display + body — одна семья) (`typography.md`) +- ✅ JetBrains Mono для metadata (issue numbers, page numbers, dates) (`typography.md`) +- ✅ **B/W minimal** + editorial red `#C8281C` accent (`color.md`) +- ✅ Асимметричный hero с SVG cover-art «after Ruskin» (`anti-patterns.md` §10) +- ✅ **Drop cap** на lede параграфе — настоящий editorial паттерн (`editorial-patterns.md` §3) +- ✅ Pull quote с правилами сверху/снизу (`editorial-patterns.md` §3) +- ✅ Section markers (§01, §02, §03) с правилами (`editorial-patterns.md` §1) +- ✅ Real-feeling content: «Marta Bellucci spent three months with one of the youngest, who is sixty-three» (`content.md`) +- ✅ Colophon в footer (`editorial-patterns.md` §1) + +--- + +#### Пример 4: Feature flag система *Latch* (SaaS / Linear-style) + +Developer tool для product teams. Sub-стиль — Linear. + +**Что применено из скиллов:** +- ✅ Dark surface `#0A0A0B` + ink `#F4F4F5` (НЕ pure black/white — `color.md` явно запрещает) +- ✅ Mint accent `#6EE7B7` — использован <10% пикселей (`color.md` §"How to Use the Accent") +- ✅ Hero asymmetric: текст слева, dashboard справа (`anti-patterns.md` §6) +- ✅ Hero headline: «Feature flags that don't get in the way.» — конкретный claim (`content.md`) +- ✅ **Dashboard mockup в CSS-only**: panel chrome, segmented control, flag rows с toggle (`product-ui-patterns.md` §1, §6) +- ✅ 3 фичи asymmetric: install (с code block) / targeting (с viz) / speed (с viz) (`anti-patterns.md` §11/12) +- ✅ Pricing: 2 честных tier'а (Hobby + Production) (`anti-patterns.md` §13) +- ✅ Footer с build info: `v3.2.7 · build 8f4a12 · uptime 99.99%` (`aesthetics.md` §6) +- ✅ Tabular numerals everywhere (font-variant-numeric) (`typography.md`) +- ✅ JavaScript: segmented control + interactive toggle (`components.md`) + +--- + +#### Пример 5: Инди-лейбл *Constellation Records* (Brutalist) + +Independent record label из Монреаля. Sub-стиль — Working Format + Bandcamp. + +**Что применено из скиллов:** +- ✅ **Marquee** с announcements (60s loop, respects `prefers-reduced-motion`) (`motion.md`) +- ✅ Pure black `#0A0A0A` + warm cream `#F4F1EB` + electric red `#FF2400` (`brutalist-patterns.md` §2) +- ✅ **Sharp corners everywhere** (`border-radius: 0`) (`brutalist-patterns.md` §"Anti-patterns") +- ✅ Hero с massive display type, italic accent в красном (`brutalist-patterns.md` §"Hallmarks") +- ✅ Hero meta column в inverted color (ink background, surface text) (`brutalist-patterns.md` §2) +- ✅ Album covers как **CSS-only abstract compositions** (concentric circles, squares) (`anti-patterns.md` §10) +- ✅ Catalog: 8 релизов, hover shifts padding + title color (`components.md`) +- ✅ **Manifesto section** с большой typography, italic emphasis в accent (`editorial-patterns.md` §1 + brutalist merge) +- ✅ Tour dates с status indicators (`ON SALE` / `SOLD OUT`) (`components.md` §"Status indicators") +- ✅ Footer в inverted color, маркеры в accent color (`brutalist-patterns.md` §2) + +--- + +#### Пример 6: Выставка *Ordnung* в Haus der Form (Swiss) + +Музейная выставка швейцарского графдизайна 1950–1980. Sub-стиль — Müller-Brockmann / International Typographic. + +**Что применено из скиллов:** +- ✅ **Ноль JavaScript** — чистые HTML + CSS (`performance.md` §"JavaScript — Ship None If You Can") +- ✅ Один гротеск Archivo throughout + IBM Plex Mono для metadata (`aesthetics.md` §3, `typography.md`) +- ✅ Hero меньше ожидаемого — `clamp(2.75rem, 6vw, 4.5rem)`, швейцарская сдержанность (`aesthetics.md` §3) +- ✅ **Type as image**: гигантские «1950→1980» с tabular-nums как визуальный якорь (`typography.md` §Numerals) +- ✅ White/pure black/один красный #D62828 — «Surface: white or black, nothing in between» (`aesthetics.md` §3) +- ✅ Meta-column паттерн 200px + 1fr во всех секциях (`layout.md` §"The meta-column pattern") +- ✅ Кнопок нет, hover у таблицы — инверсия: чёрный фон, белый текст, красный номер (`layout.md`, `components.md`) +- ✅ Реальный каталог: Müller-Brockmann «Beethoven» 1955, Neue Grafik 1–46, Ruder «Typographie» 1967 (`content.md`) +- ✅ Skip-link, semantic таблица с caption, `:focus-visible`, `prefers-reduced-motion` (`accessibility.md`) +- ✅ Карта на CSS grid-artifact вместо стоковой карты (`imagery.md` §"The vocabulary") + +--- + +## 🚀 Быстрый старт + +### 1. Клонировать + +```bash +git clone https://github.com/AkyRayy/Frontend-Design-SKILLS-for-AI.git +cd Frontend-Design-SKILLS-for-AI +``` + +### 2. Положить в контекст агента + +Зависит от платформы: + +| Платформа | Куда положить | +|---|---| +| **Claude Code / Cursor** | `.claude/skills/frontend-design/` — `SKILL.md` содержит Agent Skills frontmatter (`name` + `description`), так что скилл подхватывается автоматически | +| **Continue** | `.continue/skills/frontend-design/` | +| **Cline / Roo Code** | `.roo/skills/frontend-design/` | +| **Custom agent** | Скопировать нужные `.md` файлы в system prompt | + +### 3. Использовать + +``` +[контекст: SKILL.md + aesthetics.md + minimal-ui-patterns.md] + +Пользователь: Сделай мне лендинг для SaaS-стартапа в сфере observability. + +Агент: [читает SKILL.md, выбирает эстетику "Refined Minimal" → под-стиль "Linear"] + [определяет job страницы] + [строит токен-систему из color.md] + [пишет типографику из typography.md] + [избегает 28 паттернов из anti-patterns.md] + [пишет код в стиле code-style.md] + → выдаёт дизайн, который читается как работа старшего дизайнера +``` + +--- + +## 📘 Гайд по использованию + +### Шаг 0 — Перед началом + +Прочитайте **[SKILL.md](SKILL.md)** полностью. Это ядро. Всё остальное — детали. + +Запомните три вопроса, которые агент должен задать себе **на каждом этапе**: + +1. **Какая работа этой страницы?** (одно предложение) +2. **В какой я эстетике?** (одна, не смесь) +3. **Что должно доминировать?** (один элемент, не пять) + +### Шаг 1 — Определите работу страницы + +Без этого шага всё остальное — slop. Спросите себя: **зачем пользователь сюда пришёл и что должен сделать?** + +``` +❌ "Лендинг для нашего SaaS" → непонятно что делать +✅ "Убедить frontend engineer попробовать продукт → получить email" +✅ "Получить pre-orders для книги за $40" +✅ "Собрать заявки на работу в студию" +``` + +Запишите одно предложение. Все секции страницы должны служить этой работе. + +### Шаг 2 — Выберите эстетику + +Откройте **[aesthetics.md](aesthetics.md)**. Семь высокоуровневых эстетик: + +| Эстетика | Когда выбирать | +|---|---| +| **Refined Minimal** | SaaS, fintech, dev tools, B2B | +| **Editorial / Magazine** | Publishing, premium content, манифесты | +| **Swiss / Typographic** | Galleries, museums, архивы | +| **Brutalist / Raw** | Music, fashion, art, counterculture | +| **Soft / Hand-crafted** | Lifestyle, hospitality, indie SaaS | +| **Technical / Mono** | Dev tools, API, документация | +| **Playful / Geometric** | Consumer, kids, gaming, creative | + +**Зафиксируйте выбор. Не смешивайте два.** + +### Шаг 3 — Углубитесь в подстиль + +Откройте соответствующий файл подстилей: + +- **Refined Minimal** → [minimal-ui-patterns.md](minimal-ui-patterns.md) (11 подстилей) +- **Editorial** → [editorial-patterns.md](editorial-patterns.md) (6 подстилей) +- **Brutalist** → [brutalist-patterns.md](brutalist-patterns.md) (5 подстилей) + +Выберите конкретный подстиль (Linear, Stripe, Vercel, NYT Magazine, Bandcamp, ...) и зафиксируйте его. Не смешивайте два. + +### Шаг 4 — Соберите систему токенов + +Откройте **[color.md](color.md)** и **[typography.md](typography.md)**. Установите: + +```css +:root { + /* Палитра из color.md, конкретные hex */ + --surface: ... + --ink: ... + --accent: ... + + /* Типографика из typography.md */ + --font-display: ... + --font-text: ... + --font-mono: ... + + /* Шкала 1.25 или 1.333 */ + --text-base: 1rem; + --text-2xl: 1.953rem; + /* ... */ +} +``` + +**Никаких raw hex в компонентах.** Все цвета через токены. + +### Шаг 4½ — Задайте скелет страницы + +Откройте **[layout.md](layout.md)**. Контейнер (`1200–1280px`), spacing-шкала (`4/8/12/16/24/32/48/64/96/128`), асимметричные сплиты (`5/7`, `3/9` — не равные трети), мета-колонка, брейкпоинты `480/768/1024`. Сетка и отступы решаются до первой компоненты. + +### Шаг 5 — Избегайте slop + +Откройте **[anti-patterns.md](anti-patterns.md)**. **28 конкретных паттернов**, которые нужно отвергнуть. Каждый с примером «до» и «после». + +Перед тем как писать очередную секцию, проверьте: **не повторяю ли я один из этих 28 паттернов?** + +### Шаг 6 — Стройте компоненты правильно + +| Что строим | Где правила | +|---|---| +| Кнопки, формы, навигация | [components.md](components.md) | +| Product chrome (sidebar, command palette) | [product-ui-patterns.md](product-ui-patterns.md) | +| Иконки, изображения, favicon/og | [imagery.md](imagery.md) | +| Анимации | [motion.md](motion.md) | + +**Каждый компонент должен иметь 8 состояний:** default, hover, focus-visible, active, disabled, loading, empty, error. Без них дизайн ломается на границах. + +### Шаг 7 — Пишите конкретный контент + +Откройте **[content.md](content.md)**. Главные правила: + +| ❌ Slop | ✅ Конкретно | +|---|---| +| «Welcome to [Brand]» | «Design that doesn't need explaining.» | +| «Empowering businesses to thrive» | «Ship features 3x faster» | +| «Trusted by 10,000+» | «Used by Linear, Vercel, Stripe» | +| «Lorem ipsum» | Реальные имена, даты, цифры | + +### Шаг 8 — Пишите качественный код + +Откройте **[code-style.md](code-style.md)**. Это скилл про код — без GPT-slop в комментариях, без раздутых функций, без `any`, без магических чисел. + +**Главное правило:** имена — это дизайн. Потратьте на имя больше времени, чем на саму строку кода. + +### Шаг 8½ — Доступность и скорость + +Откройте **[accessibility.md](accessibility.md)** и **[performance.md](performance.md)**. + +- **A11y:** семантика, клавиатурный проход, `:focus-visible`, ARIA-минимализм, контраст AA — 15-минутный тест-протокол перед шипом. +- **Perf:** бюджеты (LCP < 2.5s, CLS < 0.1, ≤ 4 font-файла, ноль блокирующего JS). Страница на HTML+CSS без JS — норма, не подвиг. + +### Шаг 9 — Прогоните чеклист + +Откройте **[checklist.md](checklist.md)**. **70+ пунктов** по типографике, цвету, layout, компонентам, motion, accessibility, edge cases. + +**Финальные тесты:** + +1. Would Massimo Vignelli approve? +2. Could you ship this at Linear / Pentagram / NYT? +3. Would you screenshot this for design inspiration? +4. Would you be proud to put your name on this? + +Если 6+ ответов «нет» — продолжайте итерировать. + +--- + +## 🎯 Стратегии загрузки + +### Минимальная загрузка (быстро, минимум токенов) + +``` +1. SKILL.md ← ядро +2. aesthetics.md ← выбор эстетики +3. checklist.md ← перед релизом +``` + +### Стандартная загрузка (рекомендуется) + +``` +1. SKILL.md +2. aesthetics.md +3. typography.md +4. color.md +5. layout.md +6. checklist.md +``` + +### B2B SaaS (Linear / Stripe / Vercel) + +``` +1. SKILL.md +2. minimal-ui-patterns.md ← вместо aesthetics.md §1 +3. typography.md +4. color.md +5. layout.md +6. product-ui-patterns.md ← для sidebar, command palette и т.д. +7. accessibility.md ← интерактивный продукт поднимает планку a11y +8. checklist.md +``` + +### Editorial (Pentagram / NYT Mag) + +``` +1. SKILL.md +2. editorial-patterns.md ← вместо aesthetics.md §2 +3. typography.md +4. color.md +5. layout.md +6. checklist.md +``` + +### Brutalist (Bandcamp / Working Format) + +``` +1. SKILL.md +2. brutalist-patterns.md ← вместо aesthetics.md §4 +3. typography.md +4. checklist.md +``` + +### Продукт / интерактивное приложение + +``` +1. SKILL.md +2. minimal-ui-patterns.md +3. typography.md + color.md + layout.md +4. product-ui-patterns.md ← chrome: sidebar, ⌘K, list items, modals +5. accessibility.md ← фокус-трапы, ARIA, клавиатура +6. performance.md ← INP/CLS под нагрузкой +7. checklist.md +``` + +### Полная загрузка (глубокая работа) + +Все 18 файлов. Используется когда проект требует максимальной проработки. + +--- + +## 💎 Качество кода + +Кроме дизайна, репозиторий включает **[code-style.md](code-style.md)** — скилл для качества кода, который ИИ-агенты пишут. + +**Главные принципы:** + +| Принцип | Антипаттерн | +|---|---| +| **Имена — это дизайн** | `processData`, `doSomething`, `result` — всё это сломано | +| **Комментарии объясняют ПОЧЕМУ, не ЧТО** | `// This function adds two numbers` над `add(a, b)` | +| **Ошибки — это значения** | `catch (e) {}` молчаливо проглатывает ошибки | +| **Маленькие функции** | Функция на 200 строк с 8 параметрами | +| **Никакого `any`** | TypeScript лжёт сам себе | +| **Удаляй первым** | Прежде чем добавить код, спроси — можно ли удалить | + +**GPT-slop в коде** (catalog из 30+ паттернов): +- Комментарии «This function does X» (код уже это делает) +- Пустые `catch {}` +- `any`, `as any`, `@ts-ignore` без обоснования +- Магические числа (`0.5`, `3600`, `100`) без имён +- Функции с булевыми флагами: `doThing(x, true, false)` +- Зависимости для одной функции + +**Полный каталог и правила** → [code-style.md](code-style.md) + +--- + +## 👥 Кто это использует + +- **Разработчики ИИ-агентов** — чтобы поднять качество выхода +- **Дизайнеры, использующие ИИ** — чтобы перестать чинить одни и те же 5 паттернов +- **Разработчики без дизайнера** — чтобы AI-генерируемые сайты выглядели достойно +- **Стартаперы, которые шлют быстро** — чтобы не отправлять уродливое + +**Это не для:** дизайнеров, которые уже делают отличную работу — вы не нуждаетесь. Это для всех, кто работает downstream от LLM и хочет улучшить результат. + +--- + +## 🚫 Что это НЕ + +- **❌ Не Figma-плагин.** Это markdown-скилл для ИИ-агентов, не дизайн-инструмент для людей. +- **❌ Не CSS-фреймворк.** Не производит код; формирует код, который пишет агент. +- **❌ Не замена вкусу.** Скилл поднимает пол. Потолок — всё ещё ваш. +- **❌ Не магия.** Скилл — это инструкции. Если агент их не следует, вывод всё равно slop. + +--- + +## 🤝 Contributing + +PRы приветствуются. Особенно: + +- **Новые anti-patterns** с примерами до/после (формат в CONTRIBUTING.md) +- **Новые подстили** в `minimal-ui-patterns.md` / `editorial-patterns.md` / `brutalist-patterns.md` +- **Новые компоненты** в `product-ui-patterns.md` (HTML + CSS + все состояния) +- **Переводы** — репозиторий сейчас English-first, но Russian (этот README), Chinese, Spanish, Japanese — всё приветствуется + +**Что мы НЕ принимаем:** общие советы («используйте whitespace»), паттерны без примеров, маркетинговый язык. + +Подробности: **[CONTRIBUTING.md](CONTRIBUTING.md)** + +--- + +## 📜 Лицензия + +**[MIT](LICENSE)** — используйте, изменяйте, распространяйте. Если отправите с этим что-то хорошее — это и есть благодарность. + +--- + +## 🙏 Credits + +Паттерны взяты из работ: + +**Продуктовый дизайн:** Linear, Stripe, Vercel, Arc, Cron, Mercury, Pitch, Height, Figma, Notion, Sublime + +**Студийная работа:** Pentagram, &Walsh, DIA Studio, Manual, Working Format, Locomotive, Bureau Mirko Borsche, Studio Dumbar + +**Editorial:** NYT Magazine, Bloomberg Businessweek, It's Nice That, Wallpaper*, Apartamento, The Gentlewoman, Kinfolk + +**Swiss / International Typographic:** Müller-Brockmann, Massimo Vignelli, Jan Tschichold, Wim Crouwel, Erik Spiekermann + +**Type design:** Stefan Sagmeister, Paula Scher, Tibor Kalman, Michael Bierut + +Если узнаёте паттерны — это и есть цель. Если нет — прочитайте референсы, потом прочитайте код. + +--- + +> **Если дизайн хороший, вы его не замечаете. Если плохой — замечаете сразу.** +> +> Ваша работа — первое. Slop — второе. diff --git a/.agents/skills/frontend-design/SKILL.md b/.agents/skills/frontend-design/SKILL.md new file mode 100644 index 0000000..23f5e08 --- /dev/null +++ b/.agents/skills/frontend-design/SKILL.md @@ -0,0 +1,212 @@ +--- +name: frontend-design +description: Design-quality skill for AI agents building websites, landing pages, and web app UI. Use whenever creating or restyling any web interface that must read as designed by a senior designer, not generated. Covers aesthetics and sub-styles (Linear, Stripe, Vercel, editorial, Swiss, brutalist), typography, color tokens, layout and responsive grids, components, motion, copy, accessibility, performance, imagery, and a rejection catalog of AI-slop anti-patterns. +--- + +# SKILL: Frontend Design — Craft, Not Slop + +> A design-quality skill for AI agents building websites, web apps, and digital interfaces. Goal: output that reads as if made by a senior designer at a top studio — not by an LLM guessing at "modern web design." +> +> This file is the entry point. It is valid [Agent Skills](https://code.claude.com/docs/en/skills) format — the frontmatter above lets skill loaders (Claude Code, claude.ai) discover and activate it automatically. Supporting files are loaded by context (§7). + +--- + +## 1. Identity + +You are a **senior frontend designer-craftsman**. You treat interfaces as a craft, not a template. Your aesthetic north stars are studios and individuals who care about typography, restraint, and intent: + +- **Studios:** Pentagram, &Walsh, DIA Studio, Manual, Working Format, Locomotive, Instrument, Buck, Studio Dumbar, Bureau Cool +- **Product design:** Linear, Stripe, Vercel, Arc, Figma, Things 3, Cron, Notion Calendar +- **Editorial:** NYT Mag, Bloomberg Businessweek, It's Nice That, Wallpaper*, Apartamento, Kinfolk (the good years) +- **Type foundries & designers:** Massimo Vignelli, Wim Crouwel, Jan Tschichold, Erik Spiekermann, Stefan Sagmeister, Paula Scher, Tibor Kalman, Michael Bierut + +When in doubt: **would Massimo Vignelli approve?** Would **Linear's design team** ship this? If no — redesign. + +--- + +## 2. Core Philosophy (7 Principles) + +1. **Restraint over decoration.** Every element must earn its place. If you can remove it without losing meaning — remove it. +2. **Typography is the design.** 80% of "design quality" is type selection, sizing, hierarchy, and spacing. Pick one great typeface and use it well. +3. **One accent, many neutrals.** A site has one brand color. Everything else is a thoughtful neutral palette. Color is punctuation, not wallpaper. +4. **Whitespace is a feature.** Empty space is not "nothing" — it is composition, focus, breathing. Generous margins signal confidence. +5. **Asymmetry with intent.** Default to asymmetric layouts. Centered, symmetric everything reads as default AI output. Break the grid deliberately, not randomly. +6. **Specificity over generality.** Real content, real names, real numbers. No "Lorem ipsum." No "Welcome to our platform." No "Empowering businesses to thrive." +7. **Craft in the details.** Hover states, focus rings, transitions, edge cases, 404 pages, empty states, loading states. These are where amateurs stop and pros begin. + +--- + +## 3. AI Slop — Instant Rejection List + +**If your output contains any of these, it is rejected. Start over.** + +### Visual slop +- ❌ Purple-to-blue gradients (`#667eea → #764ba2` and friends) +- ❌ Glassmorphism on everything (`backdrop-blur`, translucent cards floating on gradients) +- ❌ Generic 3D abstract shapes / "blob" backgrounds +- ❌ Stock-style hero: smiling person + laptop + gradient overlay +- ❌ Emoji as icons (🚀 ✨ 🎉 💡 in product UI) +- ❌ `border-radius: 9999px` on every button, card, badge, image +- ❌ `box-shadow` soup: multiple stacked soft shadows making things look gummy +- ❌ Drop shadows on text (`drop-shadow` on headlines) +- ❌ "Aurora" backgrounds, mesh gradients, animated noise overlays +- ❌ Centered hero with three feature cards in a row, each with an emoji-free colored icon + +### Structural slop +- ❌ Identical 3-column feature grid repeated three times down the page +- ❌ "Hero → social proof logos → 3 features → big CTA → footer" template +- ❌ Pricing page with three identical cards, middle one "highlighted" with a glow +- ❌ FAQ with 8 questions, all starting with "What is..." / "How do..." +- ❌ Testimonial carousel with stock headshots +- ❌ Every section a horizontal banded container with rounded corners +- ❌ "Trusted by 10,000+ companies" with logos of companies that don't exist + +### Copy slop +- ❌ "Welcome to [Brand] — your one-stop solution for [abstract noun]" +- ❌ "Empowering / enabling / unlocking / supercharging" +- ❌ "Built for the modern [audience]" +- ❌ "Seamlessly integrate, effortlessly scale" +- ❌ Headlines that say nothing: "The future of work is here" +- ❌ Taglines with three adjectives stacked: "Fast. Simple. Beautiful." +- ❌ Mission statements that could apply to any company on Earth + +### Code slop +- ❌ Tailwind utility soup: 14 utilities per element, no extraction, no semantic naming +- ❌ Inline `style={{...}}` for things that should be tokens / variables +- ❌ Random hex colors not in the token system +- ❌ `font-weight: 700` on every heading regardless of family +- ❌ Default browser focus rings on form elements +- ❌ `
` soup where semantic elements exist (`
`, `
`, `