From 059ab1b1e65844d151f81c8c1e79aabb4f9975c0 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Sun, 15 Mar 2026 19:13:53 -0700 Subject: [PATCH] feat: add /typeset and /arrange skills for typography and layout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two new skills that expose frontend-design's typography and spatial design references as actionable, diagnostic workflows: - /typeset: assess and improve font choices, hierarchy, sizing, weight consistency, and readability (closes #26) - /arrange: assess and improve layout, spacing, visual rhythm, and grid structure Both follow the established skill pattern (assess → plan → execute → verify) with MANDATORY PREPARATION and context gathering. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/arrange/SKILL.md | 123 ++++++++++++++++++++++++++++++++ .claude/skills/typeset/SKILL.md | 117 ++++++++++++++++++++++++++++++ source/skills/arrange/SKILL.md | 123 ++++++++++++++++++++++++++++++++ source/skills/typeset/SKILL.md | 117 ++++++++++++++++++++++++++++++ 4 files changed, 480 insertions(+) create mode 100644 .claude/skills/arrange/SKILL.md create mode 100644 .claude/skills/typeset/SKILL.md create mode 100644 source/skills/arrange/SKILL.md create mode 100644 source/skills/typeset/SKILL.md diff --git a/.claude/skills/arrange/SKILL.md b/.claude/skills/arrange/SKILL.md new file mode 100644 index 000000000..74c21596c --- /dev/null +++ b/.claude/skills/arrange/SKILL.md @@ -0,0 +1,123 @@ +--- +name: arrange +description: Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy to create intentional compositions. +user-invokable: true +args: + - name: target + description: The feature or component to improve layout for (optional) + required: false +--- + +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 eyes — can you still identify the most important element, second most important, and clear groupings? + - Is hierarchy achieved through size alone, or through multiple dimensions? (Size + weight + color + space) + - 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) + +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](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. + +Create a systematic plan: + +- **Spacing system**: Establish a scale (4pt base: 4, 8, 12, 16, 24, 32, 48, 64, 96px) +- **Hierarchy strategy**: How will space, size, and position communicate importance? +- **Grid approach**: What structure fits the content? (Fixed grid, auto-fit, named areas) +- **Rhythm**: Where should spacing be tight vs generous? + +## Improve Layout Systematically + +### Establish a Spacing System + +- Adopt a 4pt base grid for all spacing values +- Name tokens semantically: `--space-xs`, `--space-sm`, `--space-md`, `--space-lg`, `--space-xl` +- 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 + +### Fix Grid & Structure + +- Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints +- Use named grid areas (`grid-template-areas`) for complex layouts — redefine at breakpoints +- 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 + +### Strengthen Visual Hierarchy + +- Combine dimensions: size + weight + color + space for strong hierarchy +- Surround important elements with generous whitespace — space draws attention +- Use position strategically: top-left reads as primary, bottom-right as secondary +- 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 + +- Text at `margin-left: 0` looks indented — use small negative margin to optically align +- Geometrically centered icons often look off-center — adjust visually +- Touch targets need 44px minimum regardless of visual size — use padding or pseudo-elements + +**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 +- Use the hero metric layout template (big number, small label, stats, gradient) +- Rely on size alone for hierarchy — combine size, weight, color, and space +- 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. \ No newline at end of file diff --git a/.claude/skills/typeset/SKILL.md b/.claude/skills/typeset/SKILL.md new file mode 100644 index 000000000..d768c3f7b --- /dev/null +++ b/.claude/skills/typeset/SKILL.md @@ -0,0 +1,117 @@ +--- +name: typeset +description: Improve typography by fixing font choices, hierarchy, sizing, weight consistency, and readability. Makes text feel intentional and polished. +user-invokable: true +args: + - name: target + description: The feature or component to improve typography for (optional) + required: false +--- + +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 fluid sizing used, or do sizes jump at breakpoints? + +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](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 +- **Use fluid sizing**: `clamp(min, preferred, max)` for smooth scaling + +### 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. \ No newline at end of file diff --git a/source/skills/arrange/SKILL.md b/source/skills/arrange/SKILL.md new file mode 100644 index 000000000..44f95516d --- /dev/null +++ b/source/skills/arrange/SKILL.md @@ -0,0 +1,123 @@ +--- +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 eyes — can you still identify the most important element, second most important, and clear groupings? + - Is hierarchy achieved through size alone, or through multiple dimensions? (Size + weight + color + space) + - 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) + +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](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries. + +Create a systematic plan: + +- **Spacing system**: Establish a scale (4pt base: 4, 8, 12, 16, 24, 32, 48, 64, 96px) +- **Hierarchy strategy**: How will space, size, and position communicate importance? +- **Grid approach**: What structure fits the content? (Fixed grid, auto-fit, named areas) +- **Rhythm**: Where should spacing be tight vs generous? + +## Improve Layout Systematically + +### Establish a Spacing System + +- Adopt a 4pt base grid for all spacing values +- Name tokens semantically: `--space-xs`, `--space-sm`, `--space-md`, `--space-lg`, `--space-xl` +- 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 + +### Fix Grid & Structure + +- Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints +- Use named grid areas (`grid-template-areas`) for complex layouts — redefine at breakpoints +- 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 + +### Strengthen Visual Hierarchy + +- Combine dimensions: size + weight + color + space for strong hierarchy +- Surround important elements with generous whitespace — space draws attention +- Use position strategically: top-left reads as primary, bottom-right as secondary +- 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 + +- Text at `margin-left: 0` looks indented — use small negative margin to optically align +- Geometrically centered icons often look off-center — adjust visually +- Touch targets need 44px minimum regardless of visual size — use padding or pseudo-elements + +**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 +- Use the hero metric layout template (big number, small label, stats, gradient) +- Rely on size alone for hierarchy — combine size, weight, color, and space +- 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. diff --git a/source/skills/typeset/SKILL.md b/source/skills/typeset/SKILL.md new file mode 100644 index 000000000..2bf23e183 --- /dev/null +++ b/source/skills/typeset/SKILL.md @@ -0,0 +1,117 @@ +--- +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 fluid sizing used, or do sizes jump at breakpoints? + +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](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 +- **Use fluid sizing**: `clamp(min, preferred, max)` for smooth scaling + +### 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.