learnship 1.9.9 → 1.9.11

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
   "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system. Works with Claude Code, Windsurf, Cursor, Gemini CLI, OpenCode, and Codex.",
-  "version": "1.9.9",
+  "version": "1.9.11",
   "author": {
     "name": "Favio Vazquez",
     "email": "favio.vazquezp@gmail.com"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "learnship",
   "displayName": "learnship",
   "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "1.9.9",
+  "version": "1.9.11",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/README.md

@@ -136,7 +136,7 @@ What's covered:
 - **[Getting Started](https://faviovazquez.github.io/learnship/getting-started/installation/)**: install commands, first project walkthrough, the 5 commands you need to know
 - **[Platform Guide](https://faviovazquez.github.io/learnship/platform-guide/windsurf/)**: dedicated pages for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex CLI
 - **[Core Concepts](https://faviovazquez.github.io/learnship/core-concepts/phase-loop/)**: phase loop, context engineering, planning artifacts, agentic vs vibe coding
-- **[Skills](https://faviovazquez.github.io/learnship/skills/agentic-learning/)**: all 11 `@agentic-learning` actions and all 18 `impeccable` design commands
+- **[Skills](https://faviovazquez.github.io/learnship/skills/agentic-learning/)**: all 11 `@agentic-learning` actions and all 21 `impeccable` design commands
 - **[Workflow Reference](https://faviovazquez.github.io/learnship/workflow-reference/core/)**: all 42 workflows documented with when and why to use each
 - **[Configuration](https://faviovazquez.github.io/learnship/configuration/)**: full `.planning/config.json` schema, speed presets, parallelization
 
@@ -234,7 +234,7 @@ Three integrated layers that reinforce each other:
 |-------|-------------|
 | **Workflow Engine** | Spec-driven phases → context-engineered plans → wave-ordered execution → verified delivery |
 | **Learning Partner** | Neuroscience-backed checkpoints at every phase transition: retrieval, reflection, spacing, struggle |
-| **Design System** | 18 impeccable steering commands for production-grade UI: `/audit`, `/critique`, `/polish`, and more |
+| **Design System** | 21 impeccable steering commands for production-grade UI: `/audit`, `/critique`, `/polish`, and more |
 
 ```mermaid
 graph LR
@@ -502,7 +502,7 @@ learning_mode: "manual"  → only when you explicitly invoke @agentic-learning
 
 ## 🎨 Design System
 
-The **impeccable** skill suite is always active as project context for any UI work. It provides design direction, anti-patterns, and 17 steering commands that prevent generic AI aesthetics. Based on [@pbakaus/impeccable](https://github.com/pbakaus/impeccable).
+The **impeccable** skill suite is always active as project context for any UI work. It provides design direction, anti-patterns, and 21 steering commands that prevent generic AI aesthetics. Based on [@pbakaus/impeccable](https://github.com/pbakaus/impeccable).
 
 ### Commands
 
@@ -746,7 +746,7 @@ learnship/
 │   ├── workflows/          # 42 workflows as slash commands
 │   └── skills/
 │       ├── agentic-learning/   # Learning partner (SKILL.md + references), native on Windsurf + Claude Code
-│       └── impeccable/         # Design suite: 18 skills, native on Windsurf + Claude Code
+│       └── impeccable/         # Design suite: 21 skills, native on Windsurf + Claude Code
 │           ├── frontend-design/ #   Base skill + 7 reference files (typography, color, motion…)
 │           ├── audit/           #   /audit
 │           ├── critique/        #   /critique

package/bin/install.js

@@ -608,23 +608,56 @@ function installClaudePlugins(skillsSrc, targetDir) {
     const dest = path.join(pluginSkillsDir, skillName);
 
     if (skillName === 'impeccable') {
-      // impeccable: copy root SKILL.md (rewriting sibling paths → references/ paths),
-      // then copy each sub-skill dir into references/
+      // impeccable: build a single inlined SKILL.md that contains all sub-skill
+      // content inline — same pattern as agentic-learning.
+      // Claude Code cannot follow markdown reference links to sibling files, so
+      // the hollow index approach produced an "@impeccable isn't installed" error.
       fs.mkdirSync(dest, { recursive: true });
-      let skillMdContent = fs.readFileSync(path.join(srcPath, 'SKILL.md'), 'utf8');
-      // Rewrite repo-relative sibling links (e.g. adapt/SKILL.md) to post-install references/ paths
-      skillMdContent = skillMdContent.replace(/\]\((?!references\/)([^/)][^)]*\/SKILL\.md)\)/g, '](references/$1)');
-      fs.writeFileSync(path.join(dest, 'SKILL.md'), skillMdContent);
-      const refsDest = path.join(dest, 'references');
-      fs.mkdirSync(refsDest, { recursive: true });
-      for (const sub of fs.readdirSync(srcPath, { withFileTypes: true })) {
-        if (!sub.isDirectory()) continue;
-        const subSrc = path.join(srcPath, sub.name);
-        const subDest = path.join(refsDest, sub.name);
-        if (fs.existsSync(path.join(subSrc, 'SKILL.md'))) {
-          copyDir(subSrc, subDest, '', 'claude');
-        }
+
+      // Read root frontmatter + intro (everything up to the ## Actions section)
+      const rootContent = fs.readFileSync(path.join(srcPath, 'SKILL.md'), 'utf8');
+      // Strip frontmatter, keep the prose intro + "After running" footer
+      const rootBody = rootContent.replace(/^---[\s\S]*?---\n/, '');
+
+      // Ordered sub-actions (defines appearance order in the inlined file)
+      const SUB_ACTION_ORDER = [
+        'adapt', 'animate', 'arrange', 'audit', 'bolder', 'clarify', 'colorize',
+        'critique', 'delight', 'distill', 'extract', 'frontend-design',
+        'harden', 'normalize', 'onboard', 'optimize', 'overdrive', 'polish',
+        'quieter', 'teach-impeccable', 'typeset',
+      ];
+
+      // Build inlined sections by reading each sub-skill's body
+      const inlinedSections = [];
+      for (const subName of SUB_ACTION_ORDER) {
+        const subSkillPath = path.join(srcPath, subName, 'SKILL.md');
+        if (!fs.existsSync(subSkillPath)) continue;
+        const subContent = fs.readFileSync(subSkillPath, 'utf8');
+        // Strip YAML frontmatter, keep body only
+        const subBody = subContent.replace(/^---[\s\S]*?---\n/, '').trim();
+        // Also copy sub-skill directory (for Windsurf native skill support)
+        const subDest = path.join(dest, subName);
+        copyDir(path.join(srcPath, subName), subDest, '', 'claude');
+        inlinedSections.push(`\n## Action: \`${subName}\`\n\n${subBody}`);
       }
+
+      // Root frontmatter: keep original header but update description to remove
+      // the "Invoke with @impeccable" preamble that confused Claude Code's matcher
+      const inlinedSkillMd =
+        `---\nname: impeccable\ndescription: >\n` +
+        `  A design quality system for frontend interfaces. 21 focused actions for\n` +
+        `  auditing, refining, and elevating UI quality. Use when the user asks to\n` +
+        `  audit, critique, polish, improve, review, or refine a frontend interface.\n` +
+        `  Invoke with @impeccable followed by one of: adapt, animate, arrange, audit,\n` +
+        `  bolder, clarify, colorize, critique, delight, distill, extract,\n` +
+        `  frontend-design, harden, normalize, onboard, optimize, overdrive, polish,\n` +
+        `  quieter, teach-impeccable, or typeset.\n` +
+        `---\n\n` +
+        rootBody.replace(/## Actions[\s\S]*?---\n\n## How to use/, '## How to use') +
+        `\n\n` +
+        inlinedSections.join('\n\n');
+
+      fs.writeFileSync(path.join(dest, 'SKILL.md'), inlinedSkillMd);
       count++;
     } else {
       // agentic-learning and any future top-level skills — copy verbatim
@@ -1269,6 +1302,7 @@ if (process.env.LEARNSHIP_TEST_MODE) {
     parseJsonc,
     replacePaths,
     rewriteNewProject,
+    installClaudePlugins,
     toHomePrefix,
     LEARNSHIP_CODEX_MARKER,
     CODEX_AGENT_SANDBOX,

package/cursor-rules/learnship.mdc

@@ -55,6 +55,9 @@ Read `learning_mode` from `.planning/config.json` (default: "auto"):
 
 The `impeccable` skill is available for UI work. Key commands:
 - `@impeccable audit` — full quality audit
+- `@impeccable critique` — UX effectiveness review
 - `@impeccable polish` — final pass before shipping
 - `@impeccable frontend-design` — apply design foundation principles
-- `@impeccable critique` — UX effectiveness review
+- `@impeccable arrange` — fix layout, spacing, visual rhythm
+- `@impeccable typeset` — fix typography, fonts, hierarchy
+- `@impeccable overdrive` — technically ambitious implementations

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "1.9.9",
+  "version": "1.9.11",
   "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
   "author": "Favio Vazquez",
   "homepage": "https://faviovazquez.github.io/learnship/",

package/learnship/workflows/sync-upstream-skills.md

@@ -11,7 +11,7 @@ Pull the latest skill content from both upstream repositories into learnship's s
 **What this touches:**
 - `.windsurf/skills/agentic-learning/SKILL.md` — replaced from upstream
 - `.windsurf/skills/agentic-learning/references/` — replaced from upstream
-- `.windsurf/skills/impeccable/<sub-skill>/` — each of 18 sub-skill dirs replaced from upstream
+- `.windsurf/skills/impeccable/<sub-skill>/` — each of 21 sub-skill dirs replaced from upstream
 - `.windsurf/skills/impeccable/SKILL.md` — **NOT touched** (this is learnship's own dispatcher)
 
 ---
@@ -59,7 +59,7 @@ Will pull from:
 Files updated:
   .windsurf/skills/agentic-learning/SKILL.md
   .windsurf/skills/agentic-learning/references/   (full replace)
-  .windsurf/skills/impeccable/<18 sub-skills>/    (full replace each)
+  .windsurf/skills/impeccable/<21 sub-skills>/    (full replace each)
 
 Files preserved (learnship-owned):
   .windsurf/skills/impeccable/SKILL.md            (dispatcher — never touched)
@@ -89,7 +89,7 @@ ls "$AGENTIC_LEARN_TMP"
 ls "$IMPECCABLE_TMP/source/skills/"
 ```
 
-Confirm both clones succeeded — `SKILL.md` must exist in `$AGENTIC_LEARN_TMP` and the 18 sub-skill dirs must exist under `$IMPECCABLE_TMP/source/skills/`. If either is missing, stop.
+Confirm both clones succeeded — `SKILL.md` must exist in `$AGENTIC_LEARN_TMP` and at least 21 sub-skill dirs must exist under `$IMPECCABLE_TMP/source/skills/`. If either is missing, stop.
 
 ---
 
@@ -175,7 +175,7 @@ Check all 18 expected sub-skills are present and have a `SKILL.md`:
 
 ```bash
 IMPECCABLE_DEST="$(pwd)/.windsurf/skills/impeccable"
-expected="adapt animate audit bolder clarify colorize critique delight distill extract frontend-design harden normalize onboard optimize polish quieter teach-impeccable"
+expected="adapt animate arrange audit bolder clarify colorize critique delight distill extract frontend-design harden normalize onboard optimize overdrive polish quieter teach-impeccable typeset"
 missing=""
 
 for skill in $expected; do
@@ -190,7 +190,7 @@ if [ -n "$missing" ]; then
   cp -r "$BACKUP_DIR/impeccable/." "$IMPECCABLE_DEST/"
   echo "Restored. Check upstream structure manually."
 else
-  echo "All 18 impeccable sub-skills present ✓"
+  echo "All 21 impeccable sub-skills present ✓"
 fi
 
 # Verify dispatcher is still intact
@@ -251,7 +251,7 @@ agentic-learning:
   references/    ✓ synced ([N] files)
 
 impeccable:
-  18 sub-skills  ✓ synced from pbakaus/impeccable
+  21 sub-skills  ✓ synced from pbakaus/impeccable
   SKILL.md       ✓ preserved (learnship dispatcher)
 
 All platforms updated (installer re-run):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "1.9.9",
+  "version": "1.9.11",
   "description": "Learn as you build. Build with intent. — A multi-platform agentic engineering system for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex: spec-driven workflows, integrated learning, and production-grade design.",
   "keywords": [
     "agentic",

package/skills/impeccable/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: impeccable
 description: >
-  A design quality system for frontend interfaces. 18 focused actions for
+  A design quality system for frontend interfaces. 21 focused actions for
   auditing, refining, and elevating UI quality. Invoke with @impeccable
-  followed by one of: adapt, animate, audit, bolder, clarify, colorize,
-  critique, delight, distill, extract, frontend-design, harden, normalize,
-  onboard, optimize, polish, quieter, or teach-impeccable.
+  followed by one of: adapt, animate, arrange, audit, bolder, clarify,
+  colorize, critique, delight, distill, extract, frontend-design, harden,
+  normalize, onboard, optimize, overdrive, polish, quieter, teach-impeccable,
+  or typeset.
 license: MIT
 compatibility: Works with Windsurf Cascade, Claude Code, and any AgentSkills-compatible agent.
 metadata:
@@ -15,7 +16,7 @@ metadata:
 
 # Impeccable
 
-A design quality system composed of 18 focused actions for auditing, refining,
+A design quality system composed of 21 focused actions for auditing, refining,
 and elevating frontend interfaces. Each action is a specialist — invoke the one
 that matches your current need.
 
@@ -34,6 +35,9 @@ principles and anti-patterns.
 ### `animate` — Purposeful motion & micro-interactions
 [animate/SKILL.md](animate/SKILL.md)
 
+### `arrange` — Layout, spacing & visual rhythm
+[arrange/SKILL.md](arrange/SKILL.md)
+
 ### `audit` — Comprehensive quality audit
 [audit/SKILL.md](audit/SKILL.md)
 
@@ -82,6 +86,12 @@ principles and anti-patterns.
 ### `teach-impeccable` — Project design context setup
 [teach-impeccable/SKILL.md](teach-impeccable/SKILL.md)
 
+### `typeset` — Typography: fonts, hierarchy & readability
+[typeset/SKILL.md](typeset/SKILL.md)
+
+### `overdrive` — Technically ambitious implementations
+[overdrive/SKILL.md](overdrive/SKILL.md)
+
 ---
 
 ## How to use
@@ -120,6 +130,6 @@ Or apply them directly now and use `/decision-log` to record what was changed an
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-This applies after: `audit`, `critique`, `polish`, `normalize`, `harden`, `adapt`, `optimize`, `bolder`, `quieter`, `colorize`, `clarify`, `delight`, `onboard`, `animate`, `distill`, `extract`.
+This applies after: `audit`, `critique`, `polish`, `normalize`, `harden`, `adapt`, `optimize`, `bolder`, `quieter`, `colorize`, `clarify`, `delight`, `onboard`, `animate`, `distill`, `extract`, `arrange`, `typeset`, `overdrive`.
 
 For `teach-impeccable` and `frontend-design` (which set up context, not produce recommendations), skip this suggestion.

package/skills/impeccable/arrange/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: arrange
+description: Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy to create intentional compositions.
+args:
+  - name: target
+    description: The feature or component to improve layout for (optional)
+    required: false
+user-invokable: true
+---
+
+Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak — turning generic arrangements into intentional, rhythmic compositions.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+---
+
+## Assess Current Layout
+
+Analyze what's weak about the current spatial design:
+
+1. **Spacing**:
+   - Is spacing consistent or arbitrary? (Random padding/margin values)
+   - Is all spacing the same? (Equal padding everywhere = no rhythm)
+   - Are related elements grouped tightly, with generous space between groups?
+
+2. **Visual hierarchy**:
+   - Apply the squint test: blur your (metaphorical) eyes — can you still identify the most important element, second most important, and clear groupings?
+   - Is hierarchy achieved effectively? (Space and weight alone can be enough — but is the current approach working?)
+   - Does whitespace guide the eye to what matters?
+
+3. **Grid & structure**:
+   - Is there a clear underlying structure, or does the layout feel random?
+   - Are identical card grids used everywhere? (Icon + heading + text, repeated endlessly)
+   - Is everything centered? (Left-aligned with asymmetric layouts feels more designed, but not a hard and fast rule)
+
+4. **Rhythm & variety**:
+   - Does the layout have visual rhythm? (Alternating tight/generous spacing)
+   - Is every section structured the same way? (Monotonous repetition)
+   - Are there intentional moments of surprise or emphasis?
+
+5. **Density**:
+   - Is the layout too cramped? (Not enough breathing room)
+   - Is the layout too sparse? (Excessive whitespace without purpose)
+   - Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
+
+**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material — use it with intention.
+
+## Plan Layout Improvements
+
+Consult the [spatial design reference](../frontend-design/reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries.
+
+Create a systematic plan:
+
+- **Spacing system**: Use a consistent scale — whether that's a framework's built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency.
+- **Hierarchy strategy**: How will space communicate importance?
+- **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
+- **Rhythm**: Where should spacing be tight vs generous?
+
+## Improve Layout Systematically
+
+### Establish a Spacing System
+
+- Use a consistent spacing scale — framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers.
+- Name tokens semantically if using custom properties: `--space-xs` through `--space-xl`, not `--spacing-8`
+- Use `gap` for sibling spacing instead of margins — eliminates margin collapse hacks
+- Apply `clamp()` for fluid spacing that breathes on larger screens
+
+### Create Visual Rhythm
+
+- **Tight grouping** for related elements (8-12px between siblings)
+- **Generous separation** between distinct sections (48-96px)
+- **Varied spacing** within sections — not every row needs the same gap
+- **Asymmetric compositions** — break the predictable centered-content pattern when it makes sense
+
+### Choose the Right Layout Tool
+
+- **Use Flexbox for 1D layouts**: Rows of items, nav bars, button groups, card contents, most component internals. Flex is simpler and more appropriate for the majority of layout tasks.
+- **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
+- **Don't default to Grid** when Flexbox with `flex-wrap` would be simpler and more flexible.
+- Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints.
+- Use named grid areas (`grid-template-areas`) for complex page layouts — redefine at breakpoints.
+
+### Break Card Grid Monotony
+
+- Don't default to card grids for everything — spacing and alignment create visual grouping naturally
+- Use cards only when content is truly distinct and actionable — never nest cards inside cards
+- Vary card sizes, span columns, or mix cards with non-card content to break repetition
+
+### Strengthen Visual Hierarchy
+
+- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough — generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
+- Be aware of reading flow — in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
+- Create clear content groupings through proximity and separation.
+
+### Manage Depth & Elevation
+
+- Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip)
+- Build a consistent shadow scale (sm → md → lg → xl) — shadows should be subtle
+- Use elevation to reinforce hierarchy, not as decoration
+
+### Optical Adjustments
+
+- If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively.
+
+**NEVER**:
+- Use arbitrary spacing values outside your scale
+- Make all spacing equal — variety creates hierarchy
+- Wrap everything in cards — not everything needs a container
+- Nest cards inside cards — use spacing and dividers for hierarchy within
+- Use identical card grids everywhere (icon + heading + text, repeated)
+- Center everything — left-aligned with asymmetry feels more designed
+- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work — but it should display actual data, not decorative numbers.
+- Default to CSS Grid when Flexbox would be simpler — use the simplest tool for the job
+- Use arbitrary z-index values (999, 9999) — build a semantic scale
+
+## Verify Layout Improvements
+
+- **Squint test**: Can you identify primary, secondary, and groupings with blurred vision?
+- **Rhythm**: Does the page have a satisfying beat of tight and generous spacing?
+- **Hierarchy**: Is the most important content obvious within 2 seconds?
+- **Breathing room**: Does the layout feel comfortable, not cramped or wasteful?
+- **Consistency**: Is the spacing system applied uniformly?
+- **Responsiveness**: Does the layout adapt gracefully across screen sizes?
+
+Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.

package/skills/impeccable/audit/SKILL.md

@@ -71,7 +71,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: /polish, /audit, /critique, /normalize, /colorize, /animate, /bolder, /quieter, /distill, /clarify, /optimize, /harden, /delight, /extract, /adapt, /onboard, /teach-impeccable — or other installed skills you're sure exist)
+- **Suggested command**: Which command to use (prefer: /polish, /audit, /critique, /normalize, /colorize, /animate, /bolder, /quieter, /distill, /clarify, /optimize, /harden, /delight, /extract, /adapt, /onboard, /arrange, /typeset, /overdrive, /teach-impeccable — or other installed skills you're sure exist)
 
 #### Critical Issues
 [Issues that block core functionality or violate WCAG A]
@@ -108,7 +108,7 @@ Create actionable plan:
 
 ### Suggested Commands for Fixes
 
-Map issues to available commands. Prefer these: /polish, /audit, /critique, /normalize, /colorize, /animate, /bolder, /quieter, /distill, /clarify, /optimize, /harden, /delight, /extract, /adapt, /onboard, /teach-impeccable. You may also suggest other installed skills you're sure exist, but never invent commands.
+Map issues to available commands. Prefer these: /polish, /audit, /critique, /normalize, /colorize, /animate, /bolder, /quieter, /distill, /clarify, /optimize, /harden, /delight, /extract, /adapt, /onboard, /arrange, /typeset, /overdrive, /teach-impeccable. You may also suggest other installed skills you're sure exist, but never invent commands.
 
 Examples:
 - "Use `/normalize` to align with design system (addresses N theming issues)"

package/skills/impeccable/frontend-design/SKILL.md

@@ -6,6 +6,26 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f
 
 This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
 
+## Context Gathering Protocol
+
+Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
+
+**Required context** — every design skill needs at minimum:
+- **Target audience**: Who uses this product and in what context?
+- **Use cases**: What jobs are they trying to get done?
+- **Brand personality/tone**: How should the interface feel?
+
+Individual skills may require additional context — check the skill's preparation section for specifics.
+
+**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context.
+
+**Gathering order:**
+1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
+2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
+3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run the teach-impeccable skill NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
+
+---
+
 ## Design Direction
 
 Commit to a BOLD aesthetic direction:
@@ -124,4 +144,4 @@ Match implementation complexity to the aesthetic vision. Maximalist designs need
 
 Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations.
 
-Remember: Cascade is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+Remember: You are capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

package/skills/impeccable/frontend-design/reference/typography.md

@@ -86,9 +86,11 @@ Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these override
 
 ### Fluid Type
 
-Use `clamp(min, preferred, max)` for fluid typography. The middle value (e.g., `5vw + 1rem`) controls scaling rate—higher vw = faster scaling. Add a rem offset so it doesn't collapse to 0 on small screens.
+Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport. The middle value (e.g., `5vw + 1rem`) controls scaling rate—higher vw = faster scaling. Add a rem offset so it doesn't collapse to 0 on small screens.
 
-**When NOT to use fluid type**: Button text, labels, UI elements (should be consistent), very short text, or when you need precise breakpoint control.
+**Use fluid type for**: Headings and display text on marketing/content pages where text dominates the layout and needs to breathe across viewport sizes.
+
+**Use fixed `rem` scales for**: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI — fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.
 
 ### OpenType Features
 

package/skills/impeccable/overdrive/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: overdrive
+description: Push interfaces past conventional limits with technically ambitious implementations. Whether that's a shader, a 60fps virtual table, spring physics on a dialog, or scroll-driven reveals — make users ask "how did they do that?"
+args:
+  - name: target
+    description: The feature or area to push into overdrive (optional)
+    required: false
+user-invokable: true
+---
+
+Start your response with:
+
+```
+──────────── ⚡ OVERDRIVE ─────────────
+》》》 Entering overdrive mode...
+```
+
+Push an interface past conventional limits. This isn't just about visual effects — it's about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+**EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That's extraordinary too. Understand the project's personality and goals before deciding what's appropriate.
+
+### Propose Before Building
+
+This skill has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:
+
+1. **Think through 2-3 different directions** — consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
+2. **Ask the user:** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
+3. Only proceed with the direction the user confirms.
+
+Skipping this step risks building something embarrassing that needs to be thrown away.
+
+### Iterate with Browser Automation
+
+Technically ambitious effects almost never work on the first try. You MUST actively use browser automation tools to preview your work, visually verify the result, and iterate. Do not assume the effect looks right — check it. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.
+
+---
+
+## Assess What "Extraordinary" Means Here
+
+The right kind of technical ambition depends entirely on what you're working with. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that's nice"?**
+
+### For visual/marketing surfaces
+Pages, hero sections, landing pages, portfolios — the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
+
+### For functional UI
+Tables, forms, dialogs, navigation — the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
+
+### For performance-critical UI
+The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface just never hesitates.
+
+### For data-heavy interfaces
+Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
+
+**The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around.
+
+## The Toolkit
+
+Organized by what you're trying to achieve, not by technology name.
+
+### Make transitions feel cinematic
+- **View Transitions API** (same-document: all browsers; cross-document: no Firefox) — shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
+- **`@starting-style`** (all browsers) — animate elements from `display: none` to visible with CSS only, including entry keyframes
+- **Spring physics** — natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.
+
+### Tie animation to scroll position
+- **Scroll-driven animations** (`animation-timeline: scroll()`) — CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only — always provide a static fallback)
+
+### Render beyond CSS
+- **WebGL** (all browsers) — shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express.
+- **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only) — next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
+- **Canvas 2D / OffscreenCanvas** — custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas.
+- **SVG filter chains** — displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.
+
+### Make data feel alive
+- **Virtual scrolling** — render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones.
+- **GPU-accelerated charts** — Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers.
+- **Animated data transitions** — morph between chart states rather than replacing. D3's `transition()` or View Transitions for DOM-based charts.
+
+### Animate complex properties
+- **`@property`** (all browsers) — register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate.
+- **Web Animations API** (all browsers) — JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.
+
+### Push performance boundaries
+- **Web Workers** — move computation off the main thread. Heavy data processing, image manipulation, search indexing — anything that would cause jank.
+- **OffscreenCanvas** — render in a Worker thread. The main thread stays free while complex visuals render in the background.
+- **WASM** — near-native performance for computation-heavy features. Image processing, physics simulations, codecs.
+
+### Interact with the device
+- **Web Audio API** — spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
+- **Device APIs** — orientation, ambient light, geolocation. Use sparingly and always with user permission.
+
+**NOTE**: This skill is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
+
+## Implement with Discipline
+
+### Progressive enhancement is non-negotiable
+
+Every technique must degrade gracefully. The experience without the enhancement must still be good.
+
+```css
+@supports (animation-timeline: scroll()) {
+  .hero { animation-timeline: scroll(); }
+}
+```
+
+```javascript
+if ('gpu' in navigator) { /* WebGPU */ }
+else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ }
+/* CSS-only fallback must still look good */
+```
+
+### Performance rules
+
+- Target 60fps. If dropping below 50, simplify.
+- Respect `prefers-reduced-motion` — always. Provide a beautiful static alternative.
+- Lazy-initialize heavy resources (WebGL contexts, WASM modules) only when near viewport.
+- Pause off-screen rendering. Kill what you can't see.
+- Test on real mid-range devices, not just your development machine.
+
+### Polish is the difference
+
+The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works — ship the version that feels inevitable.
+
+**NEVER**:
+- Ignore `prefers-reduced-motion` — this is an accessibility requirement, not a suggestion
+- Ship effects that cause jank on mid-range devices
+- Use bleeding-edge APIs without a functional fallback
+- Add sound without explicit user opt-in
+- Use technical ambition to mask weak design fundamentals — fix those first with other skills
+- Layer multiple competing extraordinary moments — focus creates impact, excess creates noise
+
+## Verify the Result
+
+- **The wow test**: Show it to someone who hasn't seen it. Do they react?
+- **The removal test**: Take it away. Does the experience feel diminished, or does nobody notice?
+- **The device test**: Run it on a phone, a tablet, a Chromebook. Still smooth?
+- **The accessibility test**: Enable reduced motion. Still beautiful?
+- **The context test**: Does this make sense for THIS brand and audience?
+
+Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.

package/skills/impeccable/typeset/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: typeset
+description: Improve typography by fixing font choices, hierarchy, sizing, weight consistency, and readability. Makes text feel intentional and polished.
+args:
+  - name: target
+    description: The feature or component to improve typography for (optional)
+    required: false
+user-invokable: true
+---
+
+Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
+
+## MANDATORY PREPARATION
+
+Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first.
+
+---
+
+## Assess Current Typography
+
+Analyze what's weak or generic about the current type:
+
+1. **Font choices**:
+   - Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
+   - Does the font match the brand personality? (A playful brand shouldn't use a corporate typeface)
+   - Are there too many font families? (More than 2-3 is almost always a mess)
+
+2. **Hierarchy**:
+   - Can you tell headings from body from captions at a glance?
+   - Are font sizes too close together? (14px, 15px, 16px = muddy hierarchy)
+   - Are weight contrasts strong enough? (Medium vs Regular is barely visible)
+
+3. **Sizing & scale**:
+   - Is there a consistent type scale, or are sizes arbitrary?
+   - Does body text meet minimum readability? (16px+)
+   - Is the sizing strategy appropriate for the context? (Fixed `rem` scales for app UIs; fluid `clamp()` for marketing/content page headings)
+
+4. **Readability**:
+   - Are line lengths comfortable? (45-75 characters ideal)
+   - Is line-height appropriate for the font and context?
+   - Is there enough contrast between text and background?
+
+5. **Consistency**:
+   - Are the same elements styled the same way throughout?
+   - Are font weights used consistently? (Not bold in one section, semibold in another for the same role)
+   - Is letter-spacing intentional or default everywhere?
+
+**CRITICAL**: The goal isn't to make text "fancier" — it's to make it clearer, more readable, and more intentional. Good typography is invisible; bad typography is distracting.
+
+## Plan Typography Improvements
+
+Consult the [typography reference](../frontend-design/reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies.
+
+Create a systematic plan:
+
+- **Font selection**: Do fonts need replacing? What fits the brand/context?
+- **Type scale**: Establish a modular scale (e.g., 1.25 ratio) with clear hierarchy
+- **Weight strategy**: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings — or whatever fits)
+- **Spacing**: Line-heights, letter-spacing, and margins between typographic elements
+
+## Improve Typography Systematically
+
+### Font Selection
+
+If fonts need replacing:
+- Choose fonts that reflect the brand personality
+- Pair with genuine contrast (serif + sans, geometric + humanist) — or use a single family in multiple weights
+- Ensure web font loading doesn't cause layout shift (`font-display: swap`, metric-matched fallbacks)
+
+### Establish Hierarchy
+
+Build a clear type scale:
+- **5 sizes cover most needs**: caption, secondary, body, subheading, heading
+- **Use a consistent ratio** between levels (1.25, 1.333, or 1.5)
+- **Combine dimensions**: Size + weight + color + space for strong hierarchy — don't rely on size alone
+- **App UIs**: Use a fixed `rem`-based type scale, optionally adjusted at 1-2 breakpoints. Fluid sizing undermines the spatial predictability that dense, container-based layouts need
+- **Marketing / content pages**: Use fluid sizing via `clamp(min, preferred, max)` for headings and display text. Keep body text fixed
+
+### Fix Readability
+
+- Set `max-width` on text containers using `ch` units (`max-width: 65ch`)
+- Adjust line-height per context: tighter for headings (1.1-1.2), looser for body (1.5-1.7)
+- Increase line-height slightly for light-on-dark text
+- Ensure body text is at least 16px / 1rem
+
+### Refine Details
+
+- Use `tabular-nums` for data tables and numbers that should align
+- Apply proper `letter-spacing`: slightly open for small caps and uppercase, default or tight for large display text
+- Use semantic token names (`--text-body`, `--text-heading`), not value names (`--font-16`)
+- Set `font-kerning: normal` and consider OpenType features where appropriate
+
+### Weight Consistency
+
+- Define clear roles for each weight and stick to them
+- Don't use more than 3-4 weights (Regular, Medium, Semibold, Bold is plenty)
+- Load only the weights you actually use (each weight adds to page load)
+
+**NEVER**:
+- Use more than 2-3 font families
+- Pick sizes arbitrarily — commit to a scale
+- Set body text below 16px
+- Use decorative/display fonts for body text
+- Disable browser zoom (`user-scalable=no`)
+- Use `px` for font sizes — use `rem` to respect user settings
+- Default to Inter/Roboto/Open Sans when personality matters
+- Pair fonts that are similar but not identical (two geometric sans-serifs)
+
+## Verify Typography Improvements
+
+- **Hierarchy**: Can you identify heading vs body vs caption instantly?
+- **Readability**: Is body text comfortable to read in long passages?
+- **Consistency**: Are same-role elements styled identically throughout?
+- **Personality**: Does the typography reflect the brand?
+- **Performance**: Are web fonts loading efficiently without layout shift?
+- **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
+
+Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.