@softspark/ai-toolkit 4.30.3 → 4.32.0

package/app/rules/common/git-team.md

@@ -0,0 +1,33 @@
+---
+language: common
+category: git-team
+version: "1.0.0"
+profiles:
+  - "strict"
+---
+
+# Git Team Workflow Rules
+
+These rules assume more than one person merges into `main`. They ship only with
+the `strict` profile; a solo maintainer who commits straight to `main` is not
+doing anything wrong, and a reviewer that keeps flagging "use a feature branch"
+in that setting is noise. The solo-safe core (commit format, no secrets, no
+force-push) lives in `git-workflow`.
+
+## Branching
+- Protect `main` with required reviews and CI. Never commit broken code to it.
+- Work on feature branches: `feat/user-registration`, `fix/order-total-calc`.
+- Rebase feature branches on `main` before opening a PR to keep linear history.
+- Squash fixup commits before merging to keep history clean.
+- Delete branches after merge. Stale branches are clutter.
+
+## Pull Requests
+- Keep PRs small: <400 lines changed. Split large features into stacked PRs.
+- PR title follows conventional commit format.
+- Include: summary, test plan, and screenshots/recordings for UI changes.
+- Require at least one approval before merge.
+
+## Code Review
+- Review for: correctness, security, performance, readability.
+- Approve with comments if nits only. Block for: bugs, security, missing tests.
+- Respond to reviews within 24 hours. Do not let PRs rot.

package/app/rules/common/git-workflow.md

@@ -1,11 +1,15 @@
 ---
 language: common
 category: git-workflow
-version: "1.0.0"
+version: "2.0.0"
 ---
 
 # Git Workflow Rules
 
+Solo-safe core: everything here holds whether one person or twenty merge into
+`main`. Branching, pull-request, and review conventions for teams live in
+`git-team` and ship only with the `strict` profile.
+
 ## Commit Messages
 - Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
 - First line: imperative mood, max 72 chars (`feat: add user registration endpoint`).
@@ -15,25 +19,7 @@ version: "1.0.0"
 ## Commit Practices
 - Commit small, atomic changes. One commit = one logical change.
 - Never commit: secrets, `.env` files, build artifacts, large binaries.
-- Never commit broken code to `main`. Use feature branches.
-- Squash fixup commits before merging to keep history clean.
-
-## Branching
-- `main` is always deployable. Protect it with required reviews and CI.
-- Feature branches: `feat/user-registration`, `fix/order-total-calc`.
-- Delete branches after merge. Stale branches are clutter.
-- Rebase feature branches on main before PR to keep linear history.
-
-## Pull Requests
-- Keep PRs small: <400 lines changed. Split large features into stacked PRs.
-- PR title follows conventional commit format.
-- Include: summary, test plan, and screenshots/recordings for UI changes.
-- Require at least one approval before merge.
-
-## Code Review
-- Review for: correctness, security, performance, readability.
-- Approve with comments if nits only. Block for: bugs, security, missing tests.
-- Respond to reviews within 24 hours. Do not let PRs rot.
+- `main` is always deployable: run the project's gates before every commit that lands there.
 
 ## Tags and Releases
 - Use semantic versioning: MAJOR.MINOR.PATCH.

package/app/rules/common/performance.md

@@ -1,7 +1,31 @@
 ---
 language: common
 category: performance
-version: "1.0.0"
+version: "1.1.0"
+paths:
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "**/*.go"
+  - "**/*.rs"
+  - "**/*.java"
+  - "**/*.kt"
+  - "**/*.kts"
+  - "**/*.swift"
+  - "**/*.dart"
+  - "**/*.cs"
+  - "**/*.php"
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.cxx"
+  - "**/*.hpp"
+  - "**/*.h"
+  - "**/*.rb"
+  - "**/*.sql"
 ---
 
 # Universal Performance Rules

package/app/rules/common/testing.md

@@ -1,7 +1,13 @@
 ---
 language: common
 category: testing
-version: "1.0.0"
+version: "1.1.0"
+paths:
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/test_*"
+  - "**/*_test.*"
+  - "**/tests/**"
 ---
 
 # Universal Testing Rules

package/app/rules/edit-discipline.md

@@ -0,0 +1,37 @@
+# Edit Discipline & Reviewable Changes
+
+## Edit files with the editing tools, not the shell
+
+Use the `edit` and `write` tools to change a file. Do not rewrite tracked files
+through `bash` with `sed`, `awk`, `tee`, a heredoc, or `>` redirection.
+
+This is not a style preference. A shell rewrite is opaque to the host: the
+session records a command, not a change. An `edit` call records which file
+changed and how, so the interface can render it, a reviewer can read it, and a
+later turn can cite it. A `sed` line records none of that, and the only way to
+find out what happened is to read the file again.
+
+The shell remains correct for what it is for: running builds, tests, linters,
+git, package managers, and generators that own their own output.
+
+## Show the change before calling the work done
+
+Before reporting a file-changing task as finished, show what changed:
+
+```bash
+git diff -- <paths>          # tracked files
+git status --short           # what is new or removed
+```
+
+Paste the diff into the reply, or state precisely why it is too large and
+summarise it by file with the counts. A task that reports success without
+showing the change asks the reader to take the result on trust, and the reader
+is the one who has to decide whether to commit it.
+
+For an untracked file, show the content you wrote, not a description of it.
+
+## Why both halves matter together
+
+Editing through the tools makes a change *recordable*; showing the diff makes it
+*reviewed*. Either alone leaves the person deciding whether to ship blind to
+something they are accountable for.

package/app/skills/app-builder/SKILL.md

@@ -125,17 +125,48 @@ project/
 
 ---
 
+## Design Context Gate & Pre-Flight Discipline (Web & UI Projects)
+
+Before scaffolding UI pages, establish the design foundation to avoid generic "AI slop":
+
+### 1. Design Context Gate
+Gather 3 essential dimensions (ask once, or infer with clear stated assumptions):
+- **Audience**: Who will use this? What do they care about?
+- **Use Case**: What is the single primary action the page drives? (Sign up, purchase, explore, read, configure?)
+- **Tone**: Pick an explicit extreme — *editorial, brutalist, soft, utilitarian, luxury, playful, technical, austere* ("clean and modern" is not a tone).
+
+### 2. Pre-Flight Scan (Existing Projects)
+Before generating new pages or components, scan:
+- **`design.md`** (or `DESIGN.md`) — if present, it is the locked design system and overrides defaults.
+- **Font Stack** — inspect package dependencies and CSS imports (preserve existing font pairings).
+- **Palette Tokens** — read `:root` variables, Tailwind `@theme` definitions, and OKLCH color spaces.
+- **Motion Stance** — detect installed motion libraries (`framer-motion`, `motion`, `gsap`) vs motion-cut projects.
+- **Framework & Spacing Scale** — conform to existing grid and spacing scale (4-pt / 8-pt).
+
+### 3. Structural Variety & Macrostructures
+Break the repetitive "Hero → 3 features → CTA → footer" template. Select a named whole-page macrostructure matched to the brief:
+- **Bento Grid**: Modular irregular grid where visual rhythm comes from varying card sizes and asymmetric spans.
+- **Long Document**: Literature-led, memo/journal prose format with inline section heads.
+- **Marquee Hero**: The hero fills the viewport above the fold; content shifts below the fold into a list or dense grid.
+- **Stat-Led**: A massive metric/number anchors the narrative; subsequent content qualifies the data.
+- **Workbench**: Guided product tour with real screenshots in frames; focus on functional workflow over marketing copy.
+- **Conversational FAQ**: Bold questions and honest accordion answers reading like an interview with the product.
+- **Manifesto**: Large declaration typography; establishes core philosophy before presenting product.
+- **Photographic / Quote-Led**: Led by primary imagery or borrowed credibility pull-quotes.
+
+---
+
 ## Agent Coordination
 
 ### New Project Flow
 
 ```
-1. project-planner     → Task breakdown
-2. database-architect  → Schema design
-3. backend-specialist  → API implementation
-4. frontend-specialist → UI implementation
-5. test-engineer       → Test coverage
-6. devops-implementer  → Deployment
+1. project-planner     → Task breakdown & tech selection
+2. database-architect  → Schema design & migrations
+3. backend-specialist  → API & business logic implementation
+4. frontend-specialist → UI implementation (anti-slop, 8 states)
+5. test-engineer       → Unit, integration, and E2E test coverage
+6. devops-implementer  → Deployment & CI/CD setup
 ```
 
 ### Feature Addition Flow

package/app/skills/claude-toolkit-rules/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: claude-toolkit-rules
+description: "SoftSpark working agreement: never guess a home directory path, give at least three alternatives, and apply a devil's advocate critique to decisions. Triggers: toolkit, conventions, workflow, alternatives, review."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Claude Toolkit Rules
+
+This rule comes from `app/rules/claude-toolkit-rules.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Claude Toolkit
+
+Shared AI development toolkit — lifecycle hooks, safety constitution, multi-platform support.
+
+## Skill Tiers
+
+- **Tier 1** — single-agent: `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/triage-issue`
+- **Tier 1.5** — planning: `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues`; design: `/design-an-interface`, `/architecture-audit`, `/refactor-plan`
+- **Tier 2** — multi-agent: `/workflow <type>` (feature-development, backend-feature, frontend-feature, api-design, database-evolution, test-coverage, security-audit, debugging, incident-response, spike, codebase-onboarding, performance-optimization, infrastructure-change, application-deploy, proactive-troubleshooting)
+- **Tier 3** — custom: `/orchestrate <desc>` (3–6 agents) | `/swarm <mode> <desc>` (map-reduce | consensus | relay)
+
+## Path Safety
+- NEVER guess or hallucinate user home directory paths
+- Use `~` or `$HOME` instead of a hardcoded `/Users` or `/home` prefix followed
+  by a user name. The literal prefix is deliberately not written out here: the
+  plugin export scans shipped files for exactly that pattern, so an example of
+  the mistake would be indistinguishable from the mistake.
+- When an absolute path is needed, run `echo $HOME` first to get the correct value
+
+## User Preferences
+
+- **Style:** Direct & efficient. No pleasantries. Measurable results.
+- **Methodology:** Provide >=3 alternatives. Use Socratic questioning.
+- **Review:** Apply "Devil's Advocate" critique to decisions.

package/app/skills/design-engineering/SKILL.md

@@ -16,15 +16,71 @@ Based on Emil Kowalski's design engineering philosophy — UI polish, component
 - **Invisible details create love.** Most UI refinements users never consciously register — but combined they produce something stunning.
 - **Beauty differentiates.** When functionality is table stakes, aesthetic excellence becomes genuine leverage.
 
-## Anti-Slop Visual Checklist
+## Anti-Slop Visual & Structural Checklist
 
-Defaults that signal machine-generated UI. Each is a falsifiable thing to avoid:
+Defaults that signal machine-generated UI ("AI slop"). Each is a falsifiable rule to uphold:
 
-- **Avoid** full-bleed saturated gradient backgrounds (purple-to-pink hero washes). A flat surface or a near-flat tonal shift reads as intentional; a loud gradient reads as a template.
-- **Avoid** emoji as load-bearing decoration — emoji standing in for icons, bullet markers, or section badges. Use a real icon set or typographic hierarchy instead.
-- **Avoid** the rounded-card-with-left-accent-border cliche repeated across every block. If three sections share that exact treatment, vary the layout or drop the accent.
+- **Avoid** full-bleed saturated gradient backgrounds (purple-to-pink/blue hero washes) and gradient headlines (`background-clip: text`). Use solid ink or warm neutral tinting.
+- **Avoid** emoji as load-bearing decoration (emoji as icons, bullet markers, or section badges). Use a real icon set (Lucide/Phosphor/Heroicons) or typographic hierarchy.
+- **Avoid** the 3-equal-column card grid with icon-above-heading tiles, nested cards-in-cards, or cards with thick coloured left-edge side stripes.
 - **Avoid** hand-drawn fake imagery in SVG (synthetic "photos", invented logos, faux screenshots). Use a real asset or an honest labeled placeholder.
-- **Avoid** the overused default font stack (Inter/Roboto on system-ui for everything with no scale or weight intent). Pick type with a reason and lift the actual stack from source when one exists.
+- **Avoid** fake re-drawn UI chrome (mock browser bars with traffic-light dots, mock IDE title bars, faux phone frames). Let content stand cleanly or use real screenshots in a `<figure>`.
+- **Avoid** default-attractor sameness (Hero → 3 features → CTA → footer). Pick intentional macrostructures and vary heading placement, column rhythm, and divider language.
+- **Avoid** the overused default font stack (Inter/Roboto on system-ui with no pairing). Apply the **2+1 rule** (display + body + at most 1 outlier face in <=2 slots).
+- **Avoid** italic headers: headings and display type are always roman (`font-style: normal`). Never use single-word italic emphasis inside a headline.
+
+## Pre-Emit Self-Critique (Six Axes)
+
+Before marking any UI output complete, score it 1–5 on these six axes (score <3 on any axis triggers a revision pass):
+
+| # | Axis | Assessment |
+|---|---|---|
+| **P** | **Philosophy** | Clear position and intent ("why"), not just arbitrary decoration |
+| **H** | **Hierarchy** | Clear primary / secondary / tertiary weight distinguishable in 2 seconds |
+| **E** | **Execution** | Exact rule weights, contrast ratios, focus rings, zero layout shifts |
+| **S** | **Specificity** | Tailored specifically to this brief, not a generic interchangeable template |
+| **R** | **Restraint** | Removed anything unearned (decorative bloat, redundant cards, excess padding) |
+| **V** | **Variety** | Structurally distinct from previous layouts in the project (not just a color swap) |
+
+## The 8 Interactive States Discipline
+
+Every interactive element (button, input, select, card, tab, switch) must explicitly handle all 8 states in code. Styling only default + hover is an immediate defect:
+
+| State | Trigger | Required Treatment |
+|---|---|---|
+| **1. Default** | At rest | Clean base styling, defined token bindings |
+| **2. Hover** | Pointer over (`@media (hover: hover)`) | Subtle background shift (4–6%) or 1px translate, no layout jump |
+| **3. Focus** | Keyboard navigation | Visible `:focus-visible` ring (2px solid, 1–2px offset), instant appearance |
+| **4. Active** | Pressed | Pressed-in feel: slight darken, `transform: translateY(1px)` or `scale(0.98)` |
+| **5. Disabled** | Inactive (`disabled`, `aria-disabled`) | 3 channels: `opacity: 0.55`, `cursor: not-allowed`, muted token color |
+| **6. Loading** | Async in-flight (`data-state="loading"`) | Inline spinner replacing icon/badge, label preserved, submit disabled |
+| **7. Error** | Validation failure (`aria-invalid="true"`) | Distinct error token border/message, helper text replaced, error icon |
+| **8. Success** | Operation completed (`data-state="success"`) | Quiet confirmation: subtle green/accent indicator or checkmark, auto-dismiss |
+
+## Input Fields & Zero Layout Shift
+
+Input fields, textareas, and selects are where almost-right UIs break:
+
+- **Constant border width (1px everywhere)**: Never change `border-width` between default, hover, focus, error, or disabled states. State changes go to `background-color`, `outline`, `box-shadow`, or `border-color`.
+- **Reserved transparent outline**: Initialize with `outline: 2px solid transparent; outline-offset: 1px;` so activating `:focus-visible` never shifts layout or thrashes paint.
+- **Matched component heights**: Input height MUST equal adjacent button height (base floor 44px for touch targets).
+- **Reserved helper-text slot**: Allocate `min-height: 1lh` for helper/error text so appearing validation messages do not push downstream page content.
+
+## Responsive Non-Negotiables
+
+Verify every layout at **320px, 375px, 414px, and 768px**:
+
+- **No horizontal scroll**: Apply `overflow-x: clip` (never `hidden`) on **both** `html` and `body`.
+- **Single-line clickable affordances**: Buttons, primary nav links, footer links, and CTAs must never wrap to two lines. Shorten label or reflow parent container.
+- **Image grid tracks**: Always use `minmax(0, 1fr)` instead of bare `1fr` to prevent image intrinsic dimensions from blowing out the grid.
+- **Header wrapping**: Display headers must include `overflow-wrap: anywhere; min-width: 0;`.
+
+## Locked Tokens Discipline
+
+- All colors and typography must bind to declared tokens (`var(--color-accent)`, `var(--font-display)`).
+- Never improvise inline hex / rgb / OKLCH values in components mid-build.
+- Keep accent footprint under **~5%** of viewport area (accent is for focal emphasis, not surface fill).
+- Tint neutral surfaces toward the primary anchor hue (minimum 0.005 chroma in OKLCH) — avoid flat `#000` / `#fff`.
 
 ## Minimum-Scale Floors
 
@@ -38,13 +94,13 @@ Accessibility-grounded hard thresholds. Going below these is a defect, not a sty
 
 Treat these as the lower bound, not the target. Captions and footnotes may approach the floor; primary content should sit comfortably above it.
 
-## Context-First Discipline
+## Context-First & Pre-Flight Discipline
 
-High-fidelity work MUST be rooted in real context before any pixels are produced. This mirrors the toolkit's verify-don't-recall ethos:
+High-fidelity work MUST be rooted in real context before any pixels are produced:
 
-- **Read the source first.** Inspect the codebase, design tokens, UI kit, and screenshots that already exist before generating anything.
-- **Lift exact values.** Copy real hex codes, the spacing scale, the font stack, and radii straight from source. Do NOT reconstruct token values from memory — recalled values drift.
-- **Mock from scratch only as a last resort.** Building a screen with no reference is the fallback when no codebase, kit, or screenshot exists, not the default.
+- **Run Pre-Flight Scan**: Inspect existing `design.md`, package font stacks, palette tokens (`:root`, Tailwind `@theme`), motion libraries (`framer-motion`, `motion`, `gsap`), and spacing scale.
+- **Preserve existing design systems**: Never overwrite established tokens or typography unless explicitly asked.
+- **Lift exact values**: Copy real token variable names and spacing classes straight from source. Do NOT reconstruct token values from memory.
 
 ## Question-Budget Gate
 
@@ -158,66 +214,9 @@ Exception: modals keep centered origin (viewport-anchored, not trigger-anchored)
 
 Initial tooltip includes delay; subsequent hovers skip both delay and animation via `[data-instant]` attribute — perceived speed without defeating accidental activation prevention.
 
-## Transform Mastery
-
-### Percentage translations
-
-```css
-/* Moves by own height — perfect for toasts, drawers */
-transform: translateY(100%);
-```
-
-No hardcoded pixel values needed.
-
-### Scale affects children
-
-Unlike `width`/`height`, `scale()` proportionally scales content, icons, and text. Intentional feature, not a bug.
-
-### 3D transforms
-
-```css
-.orbit {
-  transform-style: preserve-3d;
-}
-```
-
-Enables orbit animations and coin flips without JavaScript.
-
-## Clip-path Animation
-
-`clip-path: inset(top right bottom left)` creates rectangular clipping regions:
-
-### Tab color transitions
-
-Stack tab lists, clip the active copy, animate clip-path on change for seamless color shifting.
-
-### Hold-to-delete
-
-```css
-.delete-overlay {
-  clip-path: inset(0 100% 0 0);
-  transition: clip-path 200ms ease-out; /* fast snap-back on release */
-}
-.delete-button:active .delete-overlay {
-  clip-path: inset(0 0 0 0);
-  transition: clip-path 2s linear; /* slow fill while holding */
-}
-```
-
-### Image reveals
-
-```css
-.reveal {
-  clip-path: inset(0 0 100% 0); /* hidden */
-}
-.reveal.visible {
-  clip-path: inset(0 0 0 0); /* revealed */
-}
-```
-
-### Comparison sliders
+## Advanced Animation Techniques
 
-Overlay images, clip top one by adjusting right inset based on drag position.
+For advanced transform mastery, 3D orbits, and clip-path animation recipes (tabs, hold-to-delete, image reveals, sliders), see [reference/animation-recipes.md](reference/animation-recipes.md).
 
 ## Performance Rules
 
@@ -274,21 +273,7 @@ Touch triggers false hover positives — always gate hover animations.
 
 ## Building Loved Components
 
-Five principles (from Sonner, 13M+ weekly downloads):
-
-1. **Developer experience first** — minimal setup friction, insert once, use globally
-2. **Excellent defaults** — ship beautifully configured out-of-box
-3. **Identity through naming** — a memorable name resonates
-4. **Invisible edge cases** — pause timers when hidden, handle pointer capture during drag
-5. **Transitions over keyframes** — rapid additions cause keyframe restart from zero; transitions retarget smoothly
-
-### Cohesion
-
-Animation personality should match component identity. Playful components can bounce; professional dashboards stay crisp.
-
-### Asymmetric timing
-
-Deliberate actions stay slow (2s linear for hold-to-delete), system responses snap fast (200ms ease-out for release).
+For component craftsmanship principles (developer experience, defaults, edge cases, asymmetric timing), see [reference/component-craft.md](reference/component-craft.md).
 
 ## Review Checklist
 
@@ -326,26 +311,25 @@ Visual work ships through two passes, mirroring the toolkit's verification-befor
 
 - **MUST** specify exact properties in `transition` (`transition: transform 200ms ease-out`) — never `transition: all`
 - **MUST** use `ease-out` (or a custom curve) on UI appearances; `ease-in` delays feedback at the moment the user's attention peaks
-- **NEVER** animate `height`, `width`, `margin`, or `top/left` — animate `transform` and `opacity` only. Layout-triggering properties drop frames under load.
-- **NEVER** add motion for decorative reasons alone — every animation must serve meaning (status change, spatial relationship, progress)
-- **CRITICAL**: exit is faster than enter. A 2s linear enter (hold-to-delete) needs a 200ms ease-out exit. Symmetrical durations feel sluggish.
-- **MANDATORY**: any animation longer than 300ms for UI feedback needs an explicit justification — the user perceives >300ms as "laggy", not "smooth"
-- **MUST** lift exact values (hex, spacing, font stack, radii) from the real codebase, tokens, UI kit, or screenshots before high-fidelity work — never reconstruct token values from memory; mock from scratch only when no source exists
-- **MUST** keep slide body text at ~24px+, print at ~12pt+, and mobile touch targets at 44px+ — these are accessibility floors, not preferences
-- **NEVER** ship the slop defaults — saturated full-bleed gradients, emoji as decoration, repeated rounded-card-with-accent-border, hand-drawn fake imagery in SVG, or the unconsidered default font stack
-- **NEVER** add filler (dummy stats, decorative sections, lorem) to fill space, and never fabricate assets — an honest labeled placeholder beats an invented icon or fake image; ask for the real one
-- **MUST** match the existing UI's vocabulary (palette, states, motion, shadow/density, copy tone) when editing a live surface instead of imposing a new style
-- **MUST** ask about goals, audience, and which dimension to diverge on (UX vs. visuals vs. copy) before building an open-ended ask; skip questions only when context is rich and the ask is bounded
-- **CARVE-OUT**: a sanctioned design audit, accessibility-failure demonstration, or authorized red-team mockup may deliberately reproduce a slop pattern or sub-floor scale to illustrate the defect — label it as such; the bans above target shipped UI, not sanctioned analysis
-- **SHOULD** produce 3+ atomic variations across distinct axes (layout, color, type, interaction), ordered basic → advanced, for any exploratory or open design ask
+- **NEVER** animate `height`, `width`, `margin`, or `top/left` — animate `transform` and `opacity` only
+- **CRITICAL**: exit is faster than enter. A 2s linear enter (hold-to-delete) needs a 200ms ease-out exit
+- **MANDATORY**: any animation longer than 300ms for UI feedback needs an explicit justification
+- **MUST** implement all 8 interactive states (default, hover, focus-visible, active, disabled, loading, error, success) for every interactive element
+- **MUST** keep `border-width: 1px` constant across all input states (default/hover/focus/error/disabled) with a reserved transparent outline to guarantee zero layout shift
+- **MUST** apply `overflow-x: clip` on both `html` and `body` to eliminate horizontal viewport scrolling on mobile (320px–768px)
+- **MUST** ensure clickable affordance text (buttons, nav links, CTAs) remains single-line across all viewports
+- **MUST** keep all display headings roman (`font-style: normal`) — never use single-word italic emphasis inside headlines
+- **MUST** adhere to the 2+1 typography rule (max 3 families, outlier face used in at most 2 slots)
+- **MUST** lock all colors to named CSS variable tokens — never improvise inline hex/rgb/OKLCH values mid-render
+- **MUST** lift exact values (hex, spacing, font stack, radii) from real source — never reconstruct tokens from memory
+- **MUST** keep mobile touch targets at 44px+ minimum floor
+- **NEVER** ship slop defaults (purple/blue gradient hero washes, gradient text headlines, emoji as icons, cards-in-cards, side-stripe cards, centered-everything 100vh heroes)
+- **NEVER** add filler (dummy stats, fake testimonials, invented logos, lorem) — use honest labeled placeholders
+- **MUST** run pre-emit self-critique scoring (P/H/E/S/R/V) before completing UI implementation
 
 ## Gotchas
 
-- `transform: translateX(-50%)` on an element that will animate `opacity` triggers a paint on every frame because the browser cannot composite the layer. Add `will-change: transform, opacity` to hint the compositor — but only during the animation, not permanently (it consumes GPU memory).
-- Framer Motion's `x={100}` prop is a shortcut for `transform: translateX(100px)`, but under load it falls back to the main thread. Use the longhand `style={{ transform: "translateX(100px)" }}` for guaranteed compositor path.
-- `@media (prefers-reduced-motion: reduce)` is widely supported but often forgotten. Users with vestibular disorders or pointer-device sensitivity will notice; include a reduced-motion override for every non-trivial animation.
-- Chrome's Performance tab samples animations, but the sampling rate is 1kHz — sub-millisecond jank is invisible. For micro-animations, prefer `performance.mark` and `measure` with explicit timestamps.
-- CSS keyframe animations re-trigger on every class toggle. On rapidly-updating state (drag, hover), transitions are cheaper and smoother; keyframes are for one-shot entries/exits.
+For compositor edge cases, Framer Motion GPU optimizations, and reduced-motion gotchas, see [reference/animation-recipes.md](reference/animation-recipes.md).
 
 ## When NOT to Load
 
@@ -354,3 +338,4 @@ Visual work ships through two passes, mirroring the toolkit's verification-befor
 - For **information architecture** and user flows — use `/ux-designer` agent
 - For generic CSS patterns without motion — this skill is motion-specific
 - For **brand voice** / content tone — use `/brand-voice`
+

package/app/skills/design-engineering/reference/animation-recipes.md

@@ -0,0 +1,67 @@
+# Animation Recipes & Advanced Techniques
+
+Supplementary reference for `design-engineering` skill covering transform techniques, clip-path animations, and advanced interaction recipes.
+
+## Transform Mastery
+
+### Percentage Translations
+```css
+/* Moves by own height — perfect for toasts, drawers */
+transform: translateY(100%);
+```
+No hardcoded pixel values needed.
+
+### Scale Affects Children
+Unlike `width`/`height`, `scale()` proportionally scales content, icons, and text. Intentional feature, not a bug.
+
+### 3D Transforms
+```css
+.orbit {
+  transform-style: preserve-3d;
+}
+```
+Enables orbit animations and coin flips without JavaScript.
+
+---
+
+## Clip-Path Animation
+
+`clip-path: inset(top right bottom left)` creates rectangular clipping regions:
+
+### Tab Color Transitions
+Stack tab lists, clip the active copy, animate clip-path on change for seamless color shifting.
+
+### Hold-to-Delete
+```css
+.delete-overlay {
+  clip-path: inset(0 100% 0 0);
+  transition: clip-path 200ms ease-out; /* fast snap-back on release */
+}
+.delete-button:active .delete-overlay {
+  clip-path: inset(0 0 0 0);
+  transition: clip-path 2s linear; /* slow fill while holding */
+}
+```
+
+### Image Reveals
+```css
+.reveal {
+  clip-path: inset(0 0 100% 0); /* hidden */
+}
+.reveal.visible {
+  clip-path: inset(0 0 0 0); /* revealed */
+}
+```
+
+### Comparison Sliders
+Overlay images, clip top one by adjusting right inset based on drag position.
+
+---
+
+## Gotchas & Performance Edge Cases
+
+- `transform: translateX(-50%)` on an element that will animate `opacity` triggers a paint on every frame because the browser cannot composite the layer. Add `will-change: transform, opacity` during animation only.
+- Framer Motion's `x={100}` prop falls back to the main thread under load. Use `style={{ transform: "translateX(100px)" }}` for guaranteed GPU compositor path.
+- `@media (prefers-reduced-motion: reduce)` is widely supported but often forgotten; include reduced-motion overrides for every non-trivial animation.
+- Chrome's Performance tab samples animations at 1kHz — sub-millisecond jank is invisible. Prefer `performance.mark` and `measure` with explicit timestamps.
+- CSS keyframe animations re-trigger on every class toggle; transitions are cheaper and smoother on rapidly-updating state (drag, hover).

package/app/skills/design-engineering/reference/component-craft.md

@@ -0,0 +1,28 @@
+# Component Craft & Design Principles
+
+Supplementary reference for `design-engineering` skill covering principles for loved UI components and microinteraction cohesion.
+
+## Building Loved Components
+
+Five core principles (inspired by Sonner):
+
+1. **Developer experience first** — minimal setup friction, insert once, use globally
+2. **Excellent defaults** — ship beautifully configured out-of-box
+3. **Identity through naming** — a memorable name resonates
+4. **Invisible edge cases** — pause timers when hidden, handle pointer capture during drag
+5. **Transitions over keyframes** — rapid additions cause keyframe restart from zero; transitions retarget smoothly
+
+---
+
+## Personality & Cohesion
+
+Animation personality should match component identity:
+- **Playful components**: Can use slightly softer curves or playful timing.
+- **Professional tools & dashboards**: Stay crisp, deterministic, and fast (150–200ms).
+
+---
+
+## Asymmetric Timing
+
+- **Deliberate user actions**: Stay controlled/slow (e.g., 2s linear for hold-to-delete).
+- **System feedback / release**: Snaps fast (e.g., 200ms ease-out).

package/app/skills/documentation-standards/SKILL.md

@@ -47,7 +47,7 @@ and never authoritative on its own.
 |----------|-----------|---------|----------|
 | `reference` | `kb/reference/` | Technical specifications, catalogs, architecture notes, API docs | `agents-catalog.md`, `architecture-overview.md` |
 | `howto` | `kb/howto/` | Step-by-step task guides | `use-corrective-rag.md`, `configure-mcp-server.md` |
-| `procedures` | `kb/procedures/` | SOPs a person follows: release, migration, review | `maintenance-sop.md`, `sop-release.md` |
+| `procedures` | `kb/procedures/` | SOPs a person follows: release, migration, review | `sop-maintenance.md`, `sop-release.md` |
 | `troubleshooting` | `kb/troubleshooting/` | Problem resolution, debugging guides | `database-connection-issues.md` |
 | `best-practices` | `kb/best-practices/` | Guidelines, recommendations, standards | `security-checklist.md` |
 | `decisions` | `kb/decisions/` | Architecture decision records and design rationale | `adr-004-kb-migration.md` |