skills/pbakaus_impeccable
1
0
Fork 0
mirror of https://github.com/pbakaus/impeccable.git synced 2026-09-11 21:57:14 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat: add /typeset and /arrange skills for typography and layout

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
2026-03-15 19:13:53 -07:00
co-authored by Claude Opus 4.6
parent f3f4f9056a
commit 059ab1b1e6
4 changed files with 480 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/arrange/SKILL.md
+123
View File
@@ -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.
.claude/skills/typeset/SKILL.md
+117
View File
@@ -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.
source/skills/arrange/SKILL.md
+123
View File
@@ -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.
source/skills/typeset/SKILL.md
+117
View File
@@ -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.