coding-os 0.3.2__py3-none-any.whl

core/skills/docker/references/dockerfile-optimization.md

@@ -0,0 +1,64 @@
+<!-- domain:INFRA | layer:reference | ssot:true | updated:2026-06-04 -->
+# Dockerfile Optimization — Size, Cache, Base Images
+
+> P: Make images small, builds fast, and layers cacheable.
+> R: Writing or shrinking a Dockerfile; a build is slow or the image is huge.
+> S: Orchestration / registry / CI — that's [deployment-cicd](../../deployment-cicd/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [compose-patterns.md](compose-patterns.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Base image — smaller is safer
+
+| Base | Size | Use when |
+|---|---|---|
+| `*-alpine` | ~5–50 MB | static binaries, Go; musl libc (watch glibc-only deps) |
+| `*-slim` (Debian) | ~50–120 MB | most apps; glibc, no build tools |
+| `distroless` | ~20–50 MB | runtime only, no shell — hardest to exploit |
+| full (`ubuntu`, `node`) | 300 MB–1 GB | build stage only, never runtime |
+
+Pin a digest or exact version (`node:26.0.0-slim`), never `latest` — a moving
+base breaks reproducibility and silently changes your runtime.
+
+## Multi-stage — the size lever
+
+The runtime stage `COPY --from=build` only the artifact (binary, `dist/`,
+wheels). Compilers, dev dependencies, and build caches stay in the discarded
+build stage. For compiled languages the runtime can be `distroless` or `scratch`
++ a static binary — single-digit MB.
+
+## Layer cache — order + atomic RUNs
+
+- Order least-volatile → most-volatile: base → system packages → dependency
+  manifest + install → source. A change invalidates its layer and all after it.
+- One logical step per `RUN`, chained with `&&`, cleaning in the same layer:
+
+```dockerfile
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates \
+ && rm -rf /var/lib/apt/lists/*        # cleanup in the SAME layer or it still ships
+```
+
+Cleanup in a *later* `RUN` doesn't shrink the image — the earlier layer already
+recorded the files. BuildKit cache mounts (`--mount=type=cache,target=/root/.cache`)
+keep package caches across builds without baking them in.
+
+## `.dockerignore` is not optional
+
+```
+.git
+node_modules
+**/*.log
+.env
+dist
+```
+
+The build context is tar'd and sent to the daemon; without `.dockerignore` it
+includes `.git` (history!), local `node_modules`, and possibly `.env` secrets —
+slowing the build and risking a leak. Mirror `.gitignore` plus build outputs.
+
+## Measure
+
+`docker build` shows per-step timing; `docker history <image>` shows per-layer
+size — find the fat layer. `docker images` shows the total. A web app runtime
+over ~250 MB usually means the build stage leaked into runtime, or no `-slim`.

core/skills/docker/scripts/lint_dockerfile.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# lint_dockerfile.sh — PURPOSE: flag a Dockerfile against the image-craft rules.
+# INPUT: one Dockerfile path. OUTPUT: findings on stderr, "<n> issue(s)" on
+# stdout; exit 1 if any. DEPS: grep, awk. NOTES: heuristic, fail-closed; a clean
+# pass is necessary not sufficient. Spec: docs/playbooks/skill-authoring.md.
+set -euo pipefail
+IFS=$'\n\t'
+
+log() { printf '%s\n' "$*" >&2; }
+[[ $# -eq 1 ]] || { echo "usage: $0 <Dockerfile>" >&2; exit 2; }
+f="$1"
+[[ -f "$f" ]] || { echo "error: $f not found" >&2; exit 2; }
+
+issues=0
+flag() { log "  ✗ $1"; issues=$((issues + 1)); }
+
+# Untagged or :latest base image.
+if grep -iE '^[[:space:]]*FROM[[:space:]]+[^[:space:]]+(:latest)?[[:space:]]*($|AS)' "$f" \
+     | grep -ivqE ':[a-z0-9._-]+'; then
+  flag "FROM has no version tag (or uses :latest) — pin an explicit version"
+fi
+grep -iqE '^[[:space:]]*FROM[^:]*:latest' "$f" && flag "FROM uses :latest — pin a version"
+
+# Runs as root: no USER directive at all.
+grep -iqE '^[[:space:]]*USER[[:space:]]' "$f" || flag "no USER directive — container runs as root"
+
+# Secret baked via ARG/ENV (heuristic on common secret names).
+if grep -iE '^[[:space:]]*(ARG|ENV)[[:space:]]' "$f" \
+     | grep -iqE '(secret|token|password|passwd|api[_-]?key|private[_-]?key)'; then
+  flag "secret-shaped ARG/ENV — bakes the secret into image history; use --mount=type=secret"
+fi
+
+# ADD of a local path where COPY is correct (ADD line without a URL).
+if grep -iE '^[[:space:]]*ADD[[:space:]]' "$f" | grep -ivqE 'https?://'; then
+  flag "ADD used for a local file — prefer COPY (ADD auto-extracts + fetches URLs)"
+fi
+
+# apt update without cleanup in the same/any RUN.
+if grep -iqE 'apt(-get)?[[:space:]]+(update|install)' "$f" \
+   && ! grep -iqE 'rm[[:space:]]+-rf[[:space:]]+/var/lib/apt/lists' "$f"; then
+  flag "apt install without 'rm -rf /var/lib/apt/lists/*' — ships the package index"
+fi
+
+# .dockerignore alongside the Dockerfile.
+[[ -f "$(dirname "$f")/.dockerignore" ]] || log "  · no .dockerignore next to $f (ships .git/node_modules into context)"
+
+printf '%d issue(s)\n' "$issues"
+[[ "$issues" -eq 0 ]]

core/skills/docker/versions.json

@@ -0,0 +1,16 @@
+{
+  "docker-engine": {
+    "ecosystem": "github",
+    "package": "moby/moby",
+    "version": "29.5.3",
+    "source": "https://github.com/moby/moby/releases",
+    "checked": "2026-06-05"
+  },
+  "docker-compose": {
+    "ecosystem": "github",
+    "package": "docker/compose",
+    "version": "5.1.4",
+    "source": "https://github.com/docker/compose/releases",
+    "checked": "2026-06-05"
+  }
+}

core/skills/end-to-end-testing/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: end-to-end-testing
+tier: quality
+domain: [frontend, mobile]
+description: Write reliable end-to-end tests that exercise real user journeys — Playwright for web, Maestro for mobile — without the flakiness that makes teams ignore them. Use when adding an end-to-end test, debugging a flaky test, choosing what to cover end-to-end vs unit/integration, setting up CI for browser/device tests, or replacing hard sleeps and brittle selectors with reliable ones. Triggers — "end-to-end test", "e2e", "Playwright", "Maestro", "the test is flaky", "browser test", "user flow test", "test the signup flow". Pairs with testing-strategy (which test type to pick — end-to-end is the top of the pyramid, used sparingly), a11y (accessible locators double as test locators), frontend-fundamentals + mobile-fundamentals.
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# End-to-End Testing
+
+End-to-end tests are the most valuable and the most expensive tests — they prove a real user journey works across the whole stack, and they break for unrelated reasons if written carelessly. The discipline: **few but critical** journeys, **semantic** locators, **zero hard sleeps**, and **isolated** data. A flaky end-to-end suite is worse than none — teams learn to ignore red.
+
+> Lint Playwright specs for flakiness anti-patterns:
+> `python3 scripts/lint_e2e.py tests/**/*.spec.ts`
+
+## Cover journeys, not units (it's the tip of the pyramid)
+
+End-to-end tests are slow and broad — reserve them for the handful of journeys
+that, if broken, mean the product is down: sign up → log in, add to cart →
+checkout, the core create→read→update path. Everything else (edge cases, error
+states, validation) is cheaper and more reliable as unit/integration tests.
+Which test type for a given change is owned by
+[testing-strategy](../testing-strategy/SKILL.md) — this skill is how to write the
+end-to-end ones well.
+
+## Playwright — locators + auto-wait (web)
+
+```typescript
+// Wrong — brittle selector + a hard sleep = flaky and slow
+await page.waitForTimeout(3000);
+await page.click(".btn-primary.css-1x2y3z");      // generated class, breaks on rebuild
+
+// Correct — semantic locator + auto-waiting assertion
+await page.getByRole("button", { name: "Sign in" }).click();   // waits for actionable
+await expect(page.getByText("Welcome")).toBeVisible();          // retries until true or times out
+```
+
+Playwright **auto-waits** for elements to be actionable — `getByRole`/`getByLabel`/
+`getByText` plus web-first `expect` assertions retry automatically. A
+`waitForTimeout` is always wrong: either too short (flaky) or too long (slow).
+Prefer role/label/text locators (they double as accessibility checks — see
+[a11y](../a11y/SKILL.md)) over CSS/XPath. Detail → [references/playwright.md](references/playwright.md).
+
+## Maestro — flows for mobile
+
+```yaml
+# flows/login.yaml
+appId: com.example.app
+---
+- launchApp
+- tapOn: "Email"
+- inputText: "user@example.com"
+- tapOn: "Sign in"
+- assertVisible: "Welcome"
+```
+
+Maestro drives real iOS/Android (or emulators) from a declarative YAML flow. It
+has built-in retry/wait — no manual sleeps. Select by accessible text/id, not
+pixel coordinates. Detail → [references/maestro.md](references/maestro.md).
+
+## Kill flakiness at the source
+
+| Flake cause | Fix |
+|---|---|
+| hard sleep (`waitForTimeout`) | auto-waiting locator + web-first `expect` |
+| brittle selector (CSS class, nth-child) | `getByRole`/`getByTestId`/accessible text |
+| shared/leftover data between tests | each test seeds + tears down its own data |
+| test order dependence | full isolation — any test runs alone |
+| real network to third parties | mock/route external calls; control the clock |
+| race on navigation | `await` the action; let auto-wait handle readiness |
+
+A test must pass **alone and in any order**. If it needs a previous test to have
+run, it's not a test — it's a step in a script.
+
+## CI
+
+Run headless, sharded across workers (`--workers`, Playwright `--shard`),
+retries = 1–2 for true environment blips only (not to paper over flake). On
+failure, capture the **trace** (Playwright `trace: on-first-retry`) / Maestro
+recording — debugging a CI-only failure without a trace is guesswork. Pin
+versions ([versions.json](versions.json)); browsers via `playwright install`.
+
+## Anti-patterns (reject on sight)
+
+- `waitForTimeout` / `sleep` anywhere → auto-waiting assertion instead.
+- CSS/XPath selectors tied to styling or generated classes → semantic locators.
+- A test that depends on another test's data or order → isolate it.
+- Hitting real third-party APIs in an end-to-end test → mock the boundary.
+- A test with no assertion (only actions) → it proves nothing.
+- Hundreds of end-to-end tests covering edge cases → push those down to unit/integration.
+- Retries cranked to 5 to hide flake → fix the root cause.
+
+## See also
+
+- [references/playwright.md](references/playwright.md) — locators, fixtures, network mocking, traces, parallelism.
+- [references/maestro.md](references/maestro.md) — flows, selectors, CI, device matrix.
+- [assets/e2e-checklist.md](assets/e2e-checklist.md) — the ship gate.
+- [testing-strategy](../testing-strategy/SKILL.md) · [a11y](../a11y/SKILL.md).

core/skills/end-to-end-testing/assets/e2e-checklist.md

@@ -0,0 +1,23 @@
+<!-- domain:FRONTEND | layer:asset | ssot:false | updated:2026-06-04 -->
+# End-to-End Test Ship Checklist
+
+Run before adding or merging an end-to-end test.
+
+## Scope
+- [ ] Covers a critical user journey (sign-up/login, checkout, core CRUD) — not an edge case.
+- [ ] Edge cases / validation / error states pushed down to unit/integration tests.
+- [ ] The suite stays small enough to run on every PR.
+
+## Reliability
+- [ ] Zero `waitForTimeout`/`sleep` — auto-waiting locators + web-first `expect` (or Maestro implicit waits).
+- [ ] Semantic locators (`getByRole`/`getByLabel`/text / accessibility id) — no CSS-class/nth-child/coordinate selectors.
+- [ ] Each test seeds + tears down its own data; passes alone and in any order.
+- [ ] Third-party/flaky endpoints mocked (Playwright `route`) — no real external calls.
+- [ ] Every test has at least one assertion.
+- [ ] `python3 scripts/lint_e2e.py <spec files>` → `clean`.
+
+## CI
+- [ ] Headless, parallel/sharded; `retries` ≤ 2 for real blips only.
+- [ ] Trace on failure (Playwright `trace: on-first-retry` / Maestro recording).
+- [ ] Browsers/devices provisioned (`playwright install`, emulators); versions pinned.
+- [ ] `make skills-check-versions` — Playwright/Maestro pins current.

core/skills/end-to-end-testing/references/maestro.md

@@ -0,0 +1,63 @@
+<!-- domain:MOBILE | layer:reference | ssot:true | updated:2026-06-04 -->
+# Maestro — Mobile End-to-End Flows
+
+> P: Drive real iOS/Android user journeys with declarative, retry-built-in flows.
+> R: Authoring or debugging a mobile end-to-end test.
+> S: Web tests — see [playwright.md](playwright.md).
+> N: [SKILL.md](../SKILL.md), [e2e-checklist.md](../assets/e2e-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## A flow is declarative YAML
+
+```yaml
+# flows/checkout.yaml
+appId: com.example.app
+---
+- launchApp:
+    clearState: true            # isolation: start from a known state
+- tapOn: "Add to cart"
+- tapOn:
+    id: "checkout_button"       # prefer accessibility id over visible text when ambiguous
+- assertVisible: "Order confirmed"
+```
+
+Each step waits for the UI implicitly — Maestro retries `tapOn`/`assertVisible`
+until the element appears or it times out. No manual sleeps. `clearState: true`
+gives test isolation (fresh app data per flow).
+
+## Select by accessibility, not pixels
+
+```yaml
+- tapOn: "Sign in"            # visible text
+- tapOn:
+    id: "email_field"         # accessibilityIdentifier / resource-id (most stable)
+- inputText: "user@example.com"
+```
+
+Use text or the platform accessibility id (`accessibilityIdentifier` on iOS,
+`resource-id`/`contentDescription` on Android). Never tap by coordinates — it
+breaks on any layout or device change. Accessible labels make the app testable
+*and* usable (see [a11y](../../a11y/SKILL.md)).
+
+## Reuse + parameterize
+
+```yaml
+# login.yaml as a subflow
+- runFlow: login.yaml
+- runFlow:
+    file: checkout.yaml
+    env: { PRODUCT: "Book" }
+```
+
+Extract shared steps (login) into subflows; pass `env` to parameterize. Keep each
+flow one journey — a 60-step mega-flow is hard to debug when step 47 fails.
+
+## CI + debugging
+
+- `maestro test flows/` runs the suite; `maestro cloud` runs across a device
+  matrix. Record with `maestro record` to get a video of a failure.
+- Run against emulators/simulators in CI; pin the Maestro CLI version
+  ([versions.json](../versions.json)).
+- Built-in retry handles real UI timing — don't add sleeps. If a flow is flaky,
+  the selector is ambiguous or the app has a real race; fix the root cause.

core/skills/end-to-end-testing/references/playwright.md

@@ -0,0 +1,68 @@
+<!-- domain:FRONTEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# Playwright — Locators, Fixtures, Network, Traces
+
+> P: Write reliable web end-to-end tests with auto-waiting locators and isolated state.
+> R: Authoring or debugging a Playwright test.
+> S: Mobile flows — see [maestro.md](maestro.md). Test-type choice — [testing-strategy](../../testing-strategy/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [e2e-checklist.md](../assets/e2e-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Locator priority (most → least reliable)
+
+```typescript
+page.getByRole("button", { name: "Submit" })   // 1. role + accessible name (best)
+page.getByLabel("Email")                          // 2. form labels
+page.getByText("Welcome back")                    // 3. visible text
+page.getByTestId("checkout-cta")                  // 4. explicit data-testid (when no semantic anchor)
+page.locator("button.btn")                        // 5. CSS — last resort, brittle
+```
+
+Role/label/text locators also verify accessibility (a missing accessible name
+fails the test) — they couple correctness and a11y. Reserve `getByTestId` for
+elements with no semantic anchor; never select on generated CSS classes.
+
+## Auto-wait + web-first assertions
+
+```typescript
+await page.getByRole("button", { name: "Save" }).click();   // waits until actionable
+await expect(page.getByText("Saved")).toBeVisible();          // retries up to the timeout
+await expect(page).toHaveURL(/dashboard/);
+```
+
+Every action auto-waits for the element to be visible, stable, and enabled;
+`expect(locator)` retries until the condition holds. This is why
+`waitForTimeout` is never needed — the framework already waits for the *right*
+condition instead of a guessed duration.
+
+## Isolation via fixtures
+
+```typescript
+test.beforeEach(async ({ page }) => { await seedUser(); });
+test.afterEach(async () => { await cleanupUser(); });
+```
+
+Each test gets a fresh browser context (cookies/storage isolated) by default.
+Seed the data the test needs and tear it down — never rely on data a prior test
+created. Use `storageState` to skip login UI by injecting an authenticated
+session once.
+
+## Mock the boundary
+
+```typescript
+await page.route("**/api/payments", (route) =>
+  route.fulfill({ json: { status: "ok" } }));
+```
+
+Route third-party/flaky endpoints so the test controls the response — an
+end-to-end test of *your* app shouldn't fail because Stripe's sandbox is slow.
+Control time with `page.clock` for timeout/animation logic.
+
+## Debug + CI
+
+- `trace: "on-first-retry"` in config → a full DOM/network/console timeline on
+  failure; open with `npx playwright show-trace`. Debugging CI flake without it
+  is guesswork.
+- Parallelize with `fullyParallel: true` + `--workers`; shard across CI machines
+  with `--shard=1/4`. `retries: 1` for genuine blips only — not to mask flake.
+- Browsers: `npx playwright install --with-deps` in CI; pin the Playwright version.

core/skills/end-to-end-testing/scripts/lint_e2e.py

@@ -0,0 +1,88 @@
+"""Lint Playwright spec files for the common flakiness anti-patterns.
+
+PURPOSE:      Flag hard sleeps, brittle selectors, and assertion-free tests so a
+              suite stays reliable instead of teaching the team to ignore red.
+INPUT:        one or more Playwright spec paths (*.spec.ts / *.ts). [--json]
+OUTPUT:       Findings (file:line) on stderr; "clean"/"N finding(s)" on stdout.
+              Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only. Static regex scan.
+NOTES:        Heuristic — necessary not sufficient. Pure scan_text() is
+              unit-testable. Spec: docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+LINE_RULES: list[tuple[re.Pattern, str]] = [
+    (
+        re.compile(r"\bwaitForTimeout\s*\("),
+        "waitForTimeout (hard sleep) — use an auto-waiting expect",
+    ),
+    (
+        re.compile(r"\b(setTimeout|sleep)\s*\("),
+        "manual sleep — use an auto-waiting locator/assertion",
+    ),
+    (
+        re.compile(r"page\.(click|fill|type)\s*\(\s*['\"](\.|#)[\w-]*\d"),
+        "CSS selector with a generated/positional class — use getByRole/getByTestId",
+    ),
+    (
+        re.compile(r"locator\(\s*['\"][^'\"]*:nth-child"),
+        "nth-child selector — brittle; use a semantic locator",
+    ),
+    (re.compile(r"\bpage\.\$x?\("), "page.$ / page.$x (deprecated, no auto-wait) — use locators"),
+    (
+        re.compile(r"\bxpath=|\bpage\.\$x\("),
+        "XPath selector — brittle; use a role/label/text locator",
+    ),
+]
+
+TEST_DECL = re.compile(r"\b(test|it)\s*\(\s*['\"]")
+HAS_ASSERT = re.compile(r"\bexpect\s*\(")
+
+
+def scan_text(text: str, *, filename: str = "?") -> list[str]:
+    findings: list[str] = []
+    for n, line in enumerate(text.splitlines(), 1):
+        stripped = line.lstrip()
+        if stripped.startswith(("//", "*", "/*")):
+            continue
+        for pattern, msg in LINE_RULES:
+            if pattern.search(line):
+                findings.append(f"{filename}:{n}: {msg}")
+    # A spec file with test blocks but no expect() asserts nothing.
+    if TEST_DECL.search(text) and not HAS_ASSERT.search(text):
+        findings.append(f"{filename}: test(s) with no expect() — the test asserts nothing")
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    all_findings: list[str] = []
+    for path in args.files:
+        try:
+            all_findings.extend(scan_text(Path(path).read_text(encoding="utf-8"), filename=path))
+        except FileNotFoundError:
+            print(f"error: {path} not found", file=sys.stderr)
+            return 2
+
+    for f in all_findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": all_findings, "count": len(all_findings)}))
+    else:
+        print("clean" if not all_findings else f"{len(all_findings)} finding(s)")
+    return 1 if all_findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/end-to-end-testing/versions.json

@@ -0,0 +1,16 @@
+{
+  "playwright": {
+    "ecosystem": "npm",
+    "package": "playwright",
+    "version": "1.60.0",
+    "source": "https://www.npmjs.com/package/playwright",
+    "checked": "2026-06-04"
+  },
+  "maestro": {
+    "ecosystem": "github",
+    "package": "mobile-dev-inc/maestro",
+    "version": "2.6.0",
+    "source": "https://github.com/mobile-dev-inc/maestro/releases",
+    "checked": "2026-06-04"
+  }
+}

core/skills/frontend-design/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: frontend-design
+tier: quality
+domain: [frontend]
+description: Create distinctive, production-grade visual interfaces — design principles that apply to ANY frontend (React, Next.js, Vue, Svelte, plain HTML/CSS, React Native). Use when the aesthetic direction matters — building a component, page, landing site, or app where it must look intentional, not generic "AI slop". Covers visual hierarchy, spacing/rhythm, typography, color + contrast, layout, and design tokens — independent of framework. Triggers — "make this look good", "design", "UI", "landing page", "the spacing feels off", "color palette", "it looks generic/AI". Pairs with frontend-fundamentals (implementation patterns), a11y (accessibility — aesthetic without it is a lawsuit), state-management.
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+---
+
+# Frontend Design
+
+Good design looks *intentional* — every spacing value, type size, and color is a decision, not a default. This skill is the aesthetic direction, and it is **framework-independent**: the same principles apply whether you write React, Vue, Svelte, React Native, or hand-written HTML/CSS. The implementation patterns are owned by [frontend-fundamentals](../frontend-fundamentals/SKILL.md); accessibility by [a11y](../a11y/SKILL.md) — load all three for real UI work (aesthetic without a11y is a lawsuit; aesthetic without patterns is tech debt).
+
+> Check a color pair against WCAG contrast (design + a11y in one):
+> `python3 scripts/check_contrast.py "#1a1a1a" "#ffffff"`
+
+## Avoid "AI slop" — the generic look
+
+The default generic interface: even gray borders everywhere, centered everything,
+one font weight, purple-to-blue gradients, emoji as iconography, no hierarchy. It
+reads as "no decisions were made". Distinctive design makes deliberate choices: a
+real type scale, intentional asymmetry, a restrained palette with one accent,
+generous or deliberately tight spacing — consistently applied.
+
+## The principles (framework-agnostic)
+
+1. **Hierarchy** — the eye should land on the most important thing first. Achieve
+   it with size, weight, color, and space — not by making everything bold.
+2. **Spacing rhythm** — use a scale (4/8px base: 4, 8, 12, 16, 24, 32, 48, 64),
+   never arbitrary values. Consistent spacing is most of what "looks polished" is.
+3. **Typography** — a type scale (not 14 random sizes); limited weights; line-height
+   ~1.5 for body, tighter for headings; measure (line length) ~45–75 characters.
+4. **Color** — a small palette: a neutral ramp + one or two accents. Define
+   semantic roles (surface, text, primary, danger), not raw hex scattered in code.
+   Every text/background pair must pass contrast — `check_contrast.py`.
+5. **Layout** — align to a grid; respect proximity (related things close, unrelated
+   apart); use whitespace as a tool, not filler.
+
+Full treatment → [references/design-principles.md](references/design-principles.md).
+
+## Design tokens — one source of truth
+
+```
+// tokens (CSS vars / a theme object) — the SSOT for the look
+--space-1: 4px; --space-2: 8px; ... --radius: 8px;
+--color-surface: #fff; --color-text: #1a1a1a; --color-primary: #2563eb;
+```
+
+Define spacing, color, radius, type as **tokens**, reference them everywhere —
+never hardcode `margin: 13px` or `#3b82f6` inline. Tokens make the design
+consistent and themeable (dark mode = swap the token values). This is the
+api-contract-discipline principle applied to visual values.
+
+## Responsive + state, by default
+
+Design mobile-first and scale up; test the real breakpoints, not just a desktop
+width. Every interactive element needs its full state set: default, hover, focus
+(visible — a11y), active, disabled, loading, and the empty/error data states.
+A design that only shows the happy, populated, desktop view is half-designed.
+
+## Anti-patterns (reject on sight)
+
+- Arbitrary spacing (`margin: 13px`, `gap: 7px`) instead of a scale.
+- Raw hex/px scattered in components instead of tokens.
+- One font size/weight for everything → no hierarchy.
+- Centered everything, gray borders, generic gradient → AI slop.
+- Color pairs that fail contrast (looks fine to you, invisible to many).
+- Missing focus styles (removed `outline` with no replacement) → inaccessible.
+- Only the happy/populated/desktop state designed.
+
+## See also
+
+- [references/design-principles.md](references/design-principles.md) — hierarchy, spacing, type, color, layout in depth.
+- [assets/design-checklist.md](assets/design-checklist.md) — the review gate.
+- [frontend-fundamentals](../frontend-fundamentals/SKILL.md) — implementation patterns · [a11y](../a11y/SKILL.md) — accessibility · [performance](../performance/SKILL.md).

core/skills/frontend-design/assets/design-checklist.md

@@ -0,0 +1,29 @@
+<!-- domain:FRONTEND | layer:asset | ssot:false | updated:2026-06-04 -->
+# Design Review Checklist
+
+Run when reviewing the look of an interface (any framework).
+
+## Hierarchy & layout
+- [ ] One clear primary action; secondary actions visibly quieter.
+- [ ] The eye lands on the most important thing first.
+- [ ] Elements aligned to a grid; related items grouped by proximity.
+- [ ] Responsive, mobile-first; real breakpoints tested.
+
+## Spacing & type
+- [ ] All spacing from a scale (4/8 base) — no arbitrary values.
+- [ ] One type scale, limited weights; body line-height ~1.5; measure 45–75 chars.
+
+## Color & contrast
+- [ ] Small palette: neutral ramp + 1–2 accents.
+- [ ] Semantic color roles (tokens), not raw hex in components.
+- [ ] Every text/background pair passes WCAG AA — `python3 scripts/check_contrast.py <fg> <bg>` → `pass`.
+- [ ] Meaning not conveyed by color alone.
+
+## Tokens & states
+- [ ] Spacing/color/radius/type defined as tokens (one source of truth; themeable).
+- [ ] Every interactive element has default/hover/focus(visible)/active/disabled/loading states.
+- [ ] Empty + error data states designed, not just the populated happy path.
+
+## Polish
+- [ ] Doesn't read as generic "AI slop" (centered-everything, gray borders, one weight).
+- [ ] Motion (if any) communicates, is fast, respects prefers-reduced-motion.

core/skills/frontend-design/references/design-principles.md

@@ -0,0 +1,65 @@
+<!-- domain:FRONTEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# Design Principles — Hierarchy, Spacing, Type, Color, Layout
+
+> P: The visual-design fundamentals, framework-independent, that separate "intentional" from "AI slop".
+> R: Designing or reviewing any interface's look and feel.
+> S: Implementation/perf of the UI — that's [frontend-fundamentals](../../frontend-fundamentals/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [design-checklist.md](../assets/design-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Hierarchy — guide the eye
+
+The user should know where to look first without thinking. Tools, in order of
+power: **size** (bigger = more important), **weight** (bold draws), **color**
+(contrast/accent draws), **space** (isolation draws). Use the *fewest* tools that
+work — making everything bold and big destroys hierarchy. One clear primary
+action per view; secondary actions visibly quieter.
+
+## Spacing — a scale, consistently
+
+```
+4 · 8 · 12 · 16 · 24 · 32 · 48 · 64    (a 4/8px base scale)
+```
+
+Most of "looks polished" is consistent spacing. Pick a scale and never use a
+value off it (`margin: 13px` is the tell of unconsidered design). **Proximity**
+groups: related elements close, unrelated elements far. Whitespace is structure,
+not waste — crowding everything to "fit more" reads as cheap.
+
+## Typography
+
+- **One type scale** (e.g. 12, 14, 16, 20, 24, 32, 48) — not 14 arbitrary sizes.
+- **Limited weights** (regular + semibold/bold) — more looks chaotic.
+- **Line height** ~1.5 for body, ~1.1–1.25 for headings.
+- **Measure** (line length) 45–75 characters — longer is tiring, shorter is choppy.
+- **One or two typefaces** max; pair a display face with a readable body face.
+
+## Color
+
+- A **neutral ramp** (5–9 grays from near-white to near-black) carries most of the
+  UI; **one or two accents** for action/brand. Restraint reads as confident.
+- Define **semantic roles** (`surface`, `text`, `text-muted`, `primary`, `danger`,
+  `border`) — components reference roles, not raw hex.
+- **Contrast is non-negotiable**: body text ≥ 4.5:1, large text ≥ 3:1 (WCAG AA).
+  `check_contrast.py` verifies a pair. A palette that fails contrast isn't a
+  palette, it's a bug ([a11y](../../a11y/SKILL.md)).
+- Don't rely on color alone to convey meaning (color-blind users) — pair with
+  icon/text.
+
+## Layout
+
+- **Grid + alignment** — align edges; misalignment by a few px reads as sloppy
+  even when the viewer can't name why.
+- **Responsive, mobile-first** — design the small screen first, enhance up; test
+  the real breakpoints.
+- **Visual weight balance** — distribute so the composition doesn't feel lopsided;
+  intentional asymmetry beats lazy centering.
+- **Consistency** — the same component looks and behaves the same everywhere; a
+  design system / token set enforces this.
+
+## Motion (use sparingly)
+
+Animate to communicate (state change, spatial relationship), not to decorate.
+Fast (150–250ms), eased, and respect `prefers-reduced-motion`. Gratuitous motion
+is the animated cousin of AI slop.