@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/design-consistency/SKILL.md

@@ -0,0 +1,179 @@
+# Design Consistency
+
+> Internal vs. external consistency — maintaining coherent patterns within a product, adhering to platform conventions, and knowing when to break consistency deliberately
+
+## When to Use
+
+- Building a new component and deciding whether to match existing patterns or introduce a new one
+- Auditing an existing product for visual or interaction inconsistencies
+- Porting a product to a new platform (iOS to Android, web to native)
+- Debating whether a novel interaction pattern justifies breaking established conventions
+- Establishing or enforcing a design system's governance rules
+- Reviewing pull requests for design drift from documented patterns
+
+## Instructions
+
+### 1. Distinguish the Three Levels of Consistency
+
+**Internal consistency** means every screen, component, and interaction within your product behaves the same way. If cards have 8px border-radius on the dashboard, they have 8px border-radius everywhere.
+
+**External consistency** means your product behaves like other products on the same platform. iOS apps use bottom tab bars; Android apps use top navigation drawers. Users carry expectations from every other app they use daily.
+
+**Temporal consistency** means your product behaves the same way today as it did yesterday. Changing a primary button from blue to green between releases breaks the learned affordance for every existing user.
+
+**Decision procedure — when levels conflict:**
+
+1. External consistency wins when the user's safety or data is at stake. Never move a destructive action to where users expect a confirmation. Apple HIG mandates that "Delete" in action sheets is always red and positioned to require deliberate targeting.
+2. Internal consistency wins when it reinforces a unique brand interaction that users have already learned. Spotify places Shuffle as the dominant green button on every playlist — this is internally consistent even though no platform convention dictates it.
+3. Temporal consistency is the weakest constraint — you can break it during major version releases with migration cues (tooltips, onboarding overlays, changelogs).
+
+### 2. Enforce Internal Consistency with Concrete Tokens
+
+Do not rely on memory or visual inspection. Encode consistency into design tokens.
+
+**Stripe's approach:** Every interactive element uses one of exactly three border-radius values: `4px` (inputs, small elements), `6px` (cards, containers), `8px` (modals, large surfaces). There is no `12px`, no `16px`, no pill shape (`999px`). This constraint is enforced in code — the design system exports only these three radius tokens.
+
+```css
+/* Stripe-style radius tokens — exhaustive, no other values permitted */
+:root {
+  --radius-sm: 4px; /* inputs, badges, chips */
+  --radius-md: 6px; /* cards, dropdowns, popovers */
+  --radius-lg: 8px; /* modals, dialogs, sheets */
+}
+
+/* Violation — inventing a new radius */
+.fancy-button {
+  border-radius: 24px; /* WRONG: not a token, breaks consistency */
+}
+
+/* Correct — using the token */
+.fancy-button {
+  border-radius: var(--radius-sm);
+}
+```
+
+**Material Design's elevation system:** Shadows are not ad hoc. There are exactly 5 elevation levels (0dp, 1dp, 2dp, 4dp, 8dp for most components) mapped to specific component types. A card is always 1dp. A raised button is always 2dp. A dialog is always 24dp. Deviating from these creates visual noise that breaks the spatial model.
+
+### 3. Adhere to Platform Conventions (External Consistency)
+
+**The principle:** Users spend 99% of their time in other apps. Violating platform conventions forces users to relearn interactions they already know.
+
+| Convention         | iOS (Apple HIG)                     | Android (Material)                  | Web                               |
+| ------------------ | ----------------------------------- | ----------------------------------- | --------------------------------- |
+| Back navigation    | Left swipe / top-left chevron       | System back button / top-left arrow | Browser back button               |
+| Primary action     | Top-right bar button (e.g., "Done") | FAB or top-right icon               | Right-aligned button in forms     |
+| Destructive action | Red text in action sheets           | Red text in dialogs                 | Red button, requires confirmation |
+| Pull to refresh    | Native UIRefreshControl             | SwipeRefreshLayout                  | Not a convention (use button)     |
+| Tab bar position   | Bottom (max 5 tabs)                 | Top (scrollable) or bottom (3-5)    | Top (horizontal nav)              |
+
+**Airbnb's cross-platform strategy:** On iOS, Airbnb uses a bottom tab bar with 5 items (Explore, Wishlists, Trips, Inbox, Profile) matching Apple HIG. On Android, the same 5 items appear in a bottom navigation bar matching Material guidelines. The information architecture is identical; the implementation respects each platform's conventions. They do not use a hamburger menu on iOS or a bottom bar on web.
+
+### 4. Build a Consistency Audit Checklist
+
+Run this audit on every major feature or quarterly on the full product:
+
+**Visual properties:**
+
+- [ ] Border-radius: Are all values from the token set? (Grep codebase for hardcoded `px` values in `border-radius`)
+- [ ] Color: Are all colors from the palette? (No hex literals outside the token file)
+- [ ] Spacing: Are all margins/paddings multiples of the base unit? (Stripe uses 4px base; Vercel uses 8px base)
+- [ ] Typography: Are all font-size/line-height/font-weight combinations from the type scale?
+- [ ] Shadows: Are all box-shadows from the elevation token set?
+- [ ] Icons: Are all icons from the same family, same stroke weight, same optical size?
+
+**Interaction properties:**
+
+- [ ] Hover states: Do all interactive elements show the same hover treatment? (Vercel: background shifts to `--accents-2` uniformly)
+- [ ] Focus rings: Is the focus ring style identical on every focusable element?
+- [ ] Loading states: Do all async operations use the same skeleton/spinner pattern?
+- [ ] Error states: Do all errors use the same color, icon, and message position?
+- [ ] Empty states: Do all empty collections show a consistent illustration + message + CTA pattern?
+- [ ] Transitions: Are all motion durations from the timing token set? (Material: 150ms for small, 300ms for medium, 500ms for large)
+
+**Content properties:**
+
+- [ ] Capitalization: Is it sentence case or title case? (Apple: Title Case for buttons; Google: Sentence case for buttons)
+- [ ] Terminology: Is the same concept always called the same thing? ("Delete" vs. "Remove" vs. "Trash" — pick one)
+- [ ] Date formats: Is the date format consistent across all surfaces?
+- [ ] Number formats: Are currencies, percentages, and units formatted identically?
+
+### 5. Know When to Break Consistency Deliberately
+
+Consistency is not uniformity. Some situations demand breaking the pattern:
+
+**Rule: Break consistency only when the inconsistency communicates meaning.**
+
+**Worked example — Spotify's green CTA:** Every surface in Spotify uses a monochrome palette of blacks, grays, and whites. The single exception is the green (#1DB954) used exclusively for the primary action (Play, Shuffle, Follow). This deliberate inconsistency works because the break itself carries meaning — green means "this is the one thing you should do." If green appeared on 10 different element types, the signal would dissolve.
+
+**Worked example — Stripe's destructive actions:** Stripe's entire UI is composed of neutral blues and grays. Red (#FF4136) appears only on destructive actions (delete, cancel subscription, revoke key). The red breaks the color consistency to signal danger. This is a deliberate, meaningful violation.
+
+**Decision procedure for breaking consistency:**
+
+1. **Identify the signal.** What does the inconsistency communicate? If you cannot articulate it in one sentence, do not break consistency.
+2. **Verify exclusivity.** The breaking element must be the ONLY thing that looks different in that specific way. If three things are red, red no longer signals danger.
+3. **Test learnability.** After seeing the inconsistency once, can a user predict where they will see it again? Spotify users learn within minutes that green = primary action.
+4. **Document it.** Add the exception to the design system with a rationale. Undocumented exceptions become accidental inconsistencies when the next designer does not know the reasoning.
+
+## Details
+
+### Consistency Measurement
+
+Consistency is measurable, not subjective. Count the number of unique values for each visual property across the entire product:
+
+- **Border-radius:** Stripe has 3 unique values. If your product has 11, you have a consistency problem.
+- **Font sizes:** A disciplined type scale has 6-8 sizes. If your CSS contains 23 distinct `font-size` declarations, the scale is not being followed.
+- **Colors:** Vercel's dashboard uses ~12 semantic color tokens. If your product references 47 distinct hex values, the palette has drifted.
+- **Spacing:** Products on a 4px grid should show spacing values exclusively as multiples of 4. Grep for odd values (e.g., `margin: 13px`) to find violations.
+
+**Tooling for measurement:** Run `grep -roh 'border-radius: [^;]*' src/ | sort | uniq -c | sort -rn` to see every unique border-radius in the codebase. Do the same for `font-size`, `color`, `margin`, `padding`, and `box-shadow`. The output is your consistency scorecard.
+
+### Anti-Patterns
+
+**1. Snowflake components.** A designer creates a "special" card variant for a marketing page with different radius, shadow, and padding from the standard card. Another designer sees it and creates their own variant. Within 6 months, the product has 14 card variants that each appeared "justified" in isolation but collectively destroy coherence. **Fix:** Require all component variants to be added to the design system with explicit documentation of when to use each variant. If you cannot write a clear usage rule, the variant should not exist.
+
+**2. Platform denial.** Forcing iOS conventions onto Android (or vice versa) because "we want the same experience everywhere." This creates an experience that feels wrong on every platform. Users on Android expect the system back button to work; wrapping navigation in a custom stack that ignores it creates confusion. **Fix:** Share information architecture and brand identity across platforms. Adapt interaction patterns to each platform's conventions.
+
+**3. Pixel-perfect inconsistency.** The design file says buttons are 40px tall, but 30% of the buttons in production are 38px or 42px because developers eyeballed it or different developers used different base values. The eye detects these near-misses more than gross differences. **Fix:** Expose sizing tokens (not pixel values) in the component API. A button's height should be `--size-control-md`, never a raw number. Lint for hardcoded dimensional values.
+
+**4. Terminology drift.** The settings page says "Remove account," the confirmation dialog says "Delete account," and the success message says "Account erased." Three synonyms for one action across three screens. Users wonder if these are different actions. **Fix:** Maintain a terminology glossary in the design system. Each concept has exactly one canonical term. Lint content strings against the glossary.
+
+**5. Franken-pattern.** Combining conventions from different platforms or design systems in the same product — Material icons with iOS navigation with a custom Android-style FAB on web. Each piece is well-designed in its original context but together they create a disorienting experience. **Fix:** Choose one design system as the foundation and extend it. Do not mix origin systems.
+
+### Real-World Examples
+
+**Vercel — Monochrome as consistency strategy.** Vercel's entire dashboard uses exactly two hue categories: grayscale (backgrounds, text, borders) and blue (links, focus rings). There is no green success, no yellow warning, no red error in the primary UI. Status is communicated through icons and labels, not color variation. This extreme consistency means any color that does appear (like a red deployment failure badge) carries enormous visual weight precisely because it is the only chromatic element. The constraint: `--geist-foreground` (white or black depending on theme) and `--geist-background` (inverse) are the only two mandatory color tokens.
+
+**Apple — Consistency as platform trust.** Apple's HIG defines that every destructive action in an action sheet must use the `.destructive` button style (red text, standard font weight). This is consistent across every first-party and well-behaved third-party app. When a user sees red text in an action sheet, they know — without reading — that this option destroys something. Apps that use red for non-destructive actions (like "Change Color to Red") violate this convention and erode platform trust for all apps.
+
+**Material Design — Consistency through systematic constraint.** Material's component specs do not say "pick a nice shadow." They prescribe exact elevation values: FAB rests at 6dp, raised button at 2dp, card at 1dp, dialog at 24dp. The shadow values are mathematically derived from the elevation number, not hand-tuned. This system means every Material app has the same spatial hierarchy, making the platform feel cohesive even across apps from different developers.
+
+**Airbnb — Card anatomy consistency.** Every listing card across Airbnb's product follows identical anatomy: image carousel (16:9 aspect ratio), heart icon (top-right), title (semibold, 16px), subtitle (regular, 14px), metadata line (regular, 14px, secondary color), price (semibold, 16px, right-aligned). This rigid structure means users can scan hundreds of listings without cognitive overhead — their eyes know exactly where to find each piece of information. When Airbnb introduced "Experiences," the cards followed the same anatomy with different content, maintaining recognition.
+
+## Source
+
+- Apple Human Interface Guidelines: https://developer.apple.com/design/human-interface-guidelines/
+- Material Design Guidelines: https://m3.material.io/
+- Jakob Nielsen, "Consistency and Standards" (Usability Heuristic #4): https://www.nngroup.com/articles/consistency-and-standards/
+- Stripe Design System (public Stripe Sessions talks and component patterns)
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Identify which level of consistency (internal, external, temporal) is relevant to your current task.
+3. Apply the audit checklist to verify your implementation respects existing patterns.
+4. If you need to break consistency, follow the four-step decision procedure in Section 5.
+5. Document any new patterns or deliberate exceptions in the design system.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **Related skills:** Use `design-alignment` for spatial consistency, `design-gestalt-similarity` for perceptual grouping through consistent styling, `design-brand-consistency` for brand-level coherence, and `design-design-governance` for process-level enforcement.
+
+## Success Criteria
+
+- All visual properties (radius, color, spacing, typography, shadows, icons) use design tokens, not hardcoded values.
+- Platform-specific conventions are respected — the product feels native on each platform.
+- The consistency audit checklist passes with no unresolved violations.
+- Any deliberate consistency breaks are documented with a clear rationale and follow the exclusivity rule.
+- Terminology is uniform — each concept has exactly one canonical name across all surfaces.

package/dist/agents/skills/claude-code/design-consistency/skill.yaml

@@ -0,0 +1,35 @@
+name: design-consistency
+version: "1.0.0"
+description: Internal vs. external consistency — consistent patterns within a product, platform convention adherence, and when to break consistency deliberately
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-alignment
+  - design-gestalt-similarity
+  - design-brand-consistency
+  - design-design-governance
+stack_signals: []
+keywords:
+  - consistency
+  - internal-consistency
+  - external-consistency
+  - platform-conventions
+  - pattern-consistency
+  - deliberate-inconsistency
+  - audit
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/design-content-density/SKILL.md

@@ -0,0 +1,156 @@
+# Content Density
+
+> Information density as a deliberate design variable — compact, comfortable, and spacious modes, matching density to user context, and the tradeoff between showing more and showing clearly
+
+## When to Use
+
+- Deciding how much information to display per screen or viewport for a new page
+- Balancing data richness against readability in dashboards, tables, and data-heavy UIs
+- Choosing spacing, font size, and layout density for different page types within the same product
+- Implementing user-selectable density modes (compact/comfortable/spacious)
+- Evaluating whether a page feels overwhelming (too dense) or wasteful (too sparse)
+
+## Instructions
+
+1. **Treat density as a design variable, not a bug.** Density is not "how much content you crammed in" — it is a deliberate decision about information-per-viewport. Different contexts demand different densities:
+   - **High density (compact):** Expert tools, data tables, trading platforms, code editors. Users are trained, task-oriented, and want maximum information without scrolling. Bloomberg Terminal displays ~200 data points per screen. VS Code shows 40-60 lines of code with minimal chrome.
+   - **Medium density (comfortable):** Productivity apps, dashboards, email clients, project management tools. Users need overview and detail, switching between scanning and reading. Stripe Dashboard shows 8-12 data rows per table with 40px row height and 16px padding.
+   - **Low density (spacious):** Marketing pages, product showcases, onboarding flows, portfolios. Users are exploring, evaluating, or being persuaded. Apple's product pages present one idea per viewport with 60%+ whitespace.
+
+   **Decision procedure:** Ask two questions: (1) How expert is the user? (2) How many items must be compared simultaneously? Expert users comparing many items = high density. Novice users evaluating one thing = low density.
+
+2. **Apply Tufte's data-ink ratio.** Edward Tufte's principle: maximize the share of ink (pixels) used to present data; minimize the share used for non-data decoration. This is a precision tool for density optimization:
+   - **Data-ink ratio = data ink / total ink.** A ratio of 0.8+ means most pixels carry information. A ratio below 0.3 means most pixels are borders, backgrounds, decoration, or chrome.
+   - **High data-ink ratio (0.7-0.9):** Bloomberg Terminal, Google Sheets, Grafana dashboards. Almost no decorative elements — every pixel carries a data point, label, or axis line.
+   - **Medium data-ink ratio (0.4-0.6):** Stripe Dashboard, GitHub issues list, Notion pages. Balanced chrome (navigation, headers, spacing) with data content.
+   - **Low data-ink ratio (0.2-0.3):** Apple product pages, Vercel homepage, Stripe marketing. Most pixels are whitespace, images, and brand elements — the data (product specs, pricing) occupies a small fraction.
+
+   **Practical application:** For any component, count the pixels devoted to actual information vs. everything else (borders, shadows, padding, backgrounds, icons). If a data table has 300px rows with 12px of actual text content, the density is wrong — either show more data or reduce the row height.
+
+3. **Define three density modes with specific values.** When building a system that serves multiple contexts, define concrete parameters for each mode:
+
+   | Parameter        | Compact | Comfortable | Spacious   |
+   | ---------------- | ------- | ----------- | ---------- |
+   | Table row height | 32-36px | 40-48px     | 52-64px    |
+   | Card padding     | 8-12px  | 16-24px     | 24-32px    |
+   | List item height | 28-32px | 36-44px     | 48-56px    |
+   | Body font size   | 13-14px | 14-16px     | 16-18px    |
+   | Line-height      | 1.3-1.4 | 1.5-1.6     | 1.6-1.8    |
+   | Section padding  | 24-32px | 40-64px     | 80-128px   |
+   | Items visible    | 15-25   | 8-15        | 3-8        |
+   | Scroll required  | Rarely  | Sometimes   | Frequently |
+
+   Gmail implements all three: Compact (row height 28px, ~25 emails visible), Comfortable (row height 40px, ~15 emails visible), Spacious (row height 52px, ~10 emails visible). The user chooses based on their workflow.
+
+4. **Match density to page purpose.** Within a single product, different pages serve different purposes and should have different densities:
+   - **Overview/dashboard pages:** Medium density. Show key metrics, summaries, and navigation to detail views. Stripe Dashboard: 4-6 metric cards at top (spacious), transaction table below (compact). This is progressive density — sparse overview leading to dense detail.
+   - **Data/list pages:** High density. Tables, lists, search results. Users are scanning and comparing. GitHub issues list: 36px row height, 8px padding, no decorative elements.
+   - **Detail/editing pages:** Medium density. Forms, settings, individual record views. Enough space for focus, enough density for context. Figma's properties panel: comfortable density with clear section grouping.
+   - **Marketing/landing pages:** Low density. One idea per viewport, generous whitespace, large typography. Vercel homepage: each section is 400-600px tall with a single heading, subtext, and illustration.
+   - **Onboarding flows:** Low density. Reduced cognitive load, focus on one action per step. Stripe's onboarding: one form per page, maximum 3-4 inputs, 64px+ spacing between fields.
+
+5. **Implement progressive density.** Show less at first, reveal more on demand. This respects both the scanner (who needs overview) and the reader (who needs detail):
+   - **Level 1 — Overview:** Show the minimum: title, status, key metric. 1-line per item. Airbnb search results: photo, title, price, rating visible in the card.
+   - **Level 2 — Expanded:** Show supporting details on hover or click. Airbnb: clicking a listing reveals description, amenities, reviews, host info.
+   - **Level 3 — Full detail:** Show everything, often on a dedicated page. Airbnb: the full listing page with photos, map, neighborhood guide, availability calendar.
+   - **GitHub does this with issue lists:** List view shows title + labels + assignee (level 1). Clicking opens the full issue with description, comments, timeline (level 3). There is no level 2 — the jump is direct, appropriate for task-oriented expert users.
+
+6. **Adjust density for responsive viewports.** Smaller screens require density recalibration:
+   - **Mobile (compact viewport):** Increase item density slightly to compensate for reduced visible area. Show 6-8 items per screen instead of 4-5. But never reduce touch target size below 44x44px.
+   - **Tablet:** Use comfortable density — the viewport is large enough for breathing room but small enough that spacious density wastes screen.
+   - **Desktop:** Match the page purpose (see instruction 4). Large viewports can afford spacious density for marketing and comfortable density for tools.
+   - **Stripe's approach:** Dashboard tables show 12 rows on desktop (comfortable 48px rows) and 8 rows on mobile (compact 40px rows with fewer columns visible). The density increases slightly on mobile to maximize the smaller viewport.
+
+## Details
+
+### The Density Spectrum in Practice
+
+Real products mapped to the density spectrum:
+
+| Product             | Density | Row/Item Height | Items per Screen | Data-Ink Ratio |
+| ------------------- | ------- | --------------- | ---------------- | -------------- |
+| Bloomberg Terminal  | Extreme | 18-22px         | 40-60            | 0.85+          |
+| VS Code             | High    | 22px            | 40-55            | 0.75           |
+| Gmail (compact)     | High    | 28px            | 20-25            | 0.60           |
+| GitHub Issues       | Medium+ | 36px            | 12-18            | 0.55           |
+| Stripe Dashboard    | Medium  | 48px            | 8-12             | 0.50           |
+| Gmail (comfortable) | Medium  | 40px            | 12-15            | 0.50           |
+| Notion              | Medium- | 44px            | 10-14            | 0.45           |
+| Gmail (spacious)    | Low+    | 52px            | 8-10             | 0.40           |
+| Vercel Homepage     | Low     | N/A (sections)  | 1-2 ideas        | 0.25           |
+| Apple Product Page  | Minimal | N/A (sections)  | 1 idea           | 0.15           |
+
+### Density Controls: Implementation Pattern
+
+When offering user-selectable density, implement it as a single CSS custom property cascade:
+
+- Define `--density-unit` as the base multiplier (compact: 4px, comfortable: 8px, spacious: 12px)
+- All spacing derives from this unit: `padding: calc(var(--density-unit) * 2)`, `gap: var(--density-unit)`, `row-height: calc(var(--density-unit) * 5)`
+- Switch density by changing one variable. Gmail, Google Drive, and Google Calendar all use this approach.
+- Store the user's preference in localStorage or user settings — density preference is persistent and personal.
+
+### Anti-Patterns
+
+1. **One density for all contexts.** Using marketing-page spacing on a data table (massive padding, spacious rows) wastes the screen — a table that should show 20 rows shows 5, forcing excessive scrolling. Conversely, using data-table density on a landing page creates information overload where the user expects a calm, guided experience. Stripe uses spacious density on its marketing site and compact-to-comfortable density on its dashboard — same brand, different contexts.
+
+2. **Density without hierarchy.** Cramming content into a small space without establishing visual priority creates a wall of text. High density does not mean "everything the same size and weight" — it means more information with clear hierarchy. Bloomberg Terminal is extremely dense but uses color coding, bold text, borders, and spatial grouping to maintain scannability. Without these hierarchy tools, density becomes chaos.
+
+3. **User-hostile density.** Defaulting to compact density with no option to increase spacing. Not all users are power users — new users, users with visual impairments, and users on touch devices need more space. Gmail defaults to "comfortable" and offers compact/spacious as options. Material Design 3 specifies that compact density should never be the default — it is an opt-in for experienced users.
+
+4. **Ignoring the scroll cost.** Spacious density means more scrolling. For data comparison tasks, scrolling is expensive — the user loses context of items above the fold. A data table with 64px rows showing 5 items per screen forces constant scrolling to compare 20 items. For this context, 32px rows showing 15+ items reduces scroll cost by 60% and improves comparison efficiency.
+
+5. **Responsive density mismatch.** Keeping desktop density on mobile. A comfortable-density dashboard (48px rows) on a 667px-tall mobile screen shows only 8-9 rows after accounting for navigation and header. Switching to compact (36px rows) shows 12-13 rows — a 40% increase in visible data that materially improves the mobile experience.
+
+### Real-World Examples
+
+**Bloomberg Terminal (Expert Density):**
+
+- Row height: 18-22px with 2px padding
+- Font: 11-13px monospace, tight line-height (1.2)
+- No decorative whitespace — every pixel is data, label, or separator
+- Color-coded: green for positive, red for negative, blue for interactive
+- Appropriate because users spend 8+ hours daily and have months of training
+- Would be catastrophic for a consumer-facing product
+
+**Stripe Dashboard (Balanced Density):**
+
+- Table rows: 48px height with 16px horizontal padding
+- Metric cards: 32px padding, 24px gap between cards
+- Charts: 200-240px tall with 16px padding, labeled axes
+- Body text: 14px at 1.5 line-height — readable without being spacious
+- Navigation: 40px item height, 8px gap between items
+- Progressive: overview page is medium density; clicking into a payment shows comfortable detail density
+
+**Apple Product Pages (Minimal Density):**
+
+- One idea per viewport (400-700px section height for a single heading + image)
+- Body text: 21px at 1.47 line-height — larger than most web body text
+- Section padding: 100-120px top and bottom
+- Product comparison: spacious on desktop, transforms to a swipeable card carousel on mobile to maintain density appropriate to the interaction model
+- Whitespace-to-content ratio: approximately 3:1
+
+## Source
+
+- Edward Tufte, "The Visual Display of Quantitative Information" — data-ink ratio and information density theory
+- Material Design 3 density guidelines (m3.material.io/foundations/layout/density)
+- Nielsen Norman Group, "Information Density in Design" — research on scanning patterns and density thresholds
+- Stephen Few, "Information Dashboard Design" — dashboard-specific density principles
+
+## Process
+
+1. **Classify** the page purpose (data, overview, detail, marketing, onboarding) to determine the target density zone
+2. **Define** concrete density parameters (row height, padding, font size, items per screen) from the density table
+3. **Validate** by counting visible items per screen and measuring the data-ink ratio — adjust if the numbers fall outside the target zone
+
+## Harness Integration
+
+This is a knowledge skill. When activated, its content is injected into the system prompt to guide density decisions. It does not execute code or modify files. Use alongside `design-whitespace` for spacing scale definition, `design-readability` for typography density interaction, and `design-responsive-strategy` for viewport-specific density adaptation.
+
+## Success Criteria
+
+- Every page has a declared density mode (compact, comfortable, or spacious) matched to its purpose
+- Density parameters (row height, padding, font size) are explicitly defined, not accidental
+- Data-heavy pages have a data-ink ratio above 0.5; marketing pages can be below 0.3
+- Progressive density is implemented: overview is sparser, detail is denser
+- If user-selectable density is offered, comfortable is the default with compact as opt-in
+- Responsive viewports adjust density appropriately (slightly denser on mobile to maximize limited viewport)

package/dist/agents/skills/claude-code/design-content-density/skill.yaml

@@ -0,0 +1,34 @@
+name: design-content-density
+version: "1.0.0"
+description: Information density tradeoffs — compact vs. comfortable vs. spacious, data-dense vs. marketing
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-whitespace
+  - design-readability
+  - design-responsive-strategy
+stack_signals: []
+keywords:
+  - content density
+  - information density
+  - compact
+  - comfortable
+  - spacious
+  - data-dense
+  - scanability
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/design-contrast-ratio/SKILL.md

@@ -0,0 +1,151 @@
+# Contrast Ratio
+
+> Luminance contrast for readability and visual weight — WCAG ratios, contrast as a hierarchy tool, contrast beyond accessibility
+
+## When to Use
+
+- Setting text colors against backgrounds for any UI element
+- Designing visual hierarchy through contrast tiers (primary, secondary, tertiary content)
+- Evaluating whether interactive elements (buttons, links, form controls) are sufficiently visible
+- Building or auditing a design system's contrast scale
+- Choosing colors for data visualization labels, chart annotations, or overlay text
+- Assessing dark mode palettes for adequate contrast without eye strain
+- Reviewing designs for WCAG 2.1 AA or AAA compliance
+- Verifying focus indicators and interactive state visibility
+- Calibrating overlay opacity for text on images or gradients
+- Defining a contrast scale for a design token system
+- Ensuring disabled states are perceivable but visually de-emphasized
+
+## Instructions
+
+1. **Know the WCAG thresholds.** These are non-negotiable minimums, not targets:
+
+   | Content Type                                                 | AA Minimum     | AAA Enhanced | Example                                        |
+   | ------------------------------------------------------------ | -------------- | ------------ | ---------------------------------------------- |
+   | Normal text (<18pt / <24px, or <14pt bold / <18.5px bold)    | 4.5:1          | 7:1          | Body copy, labels, captions                    |
+   | Large text (>=18pt / >=24px, or >=14pt bold / >=18.5px bold) | 3:1            | 4.5:1        | Headings, hero text                            |
+   | Non-text UI components (icons, borders, form outlines)       | 3:1            | —            | Checkbox borders, input outlines, icon buttons |
+   | Inactive components and decorative elements                  | No requirement | —            | Disabled buttons, background patterns          |
+
+2. **Understand relative luminance.** Contrast ratio is calculated from relative luminance, not perceived brightness. The formula: `(L1 + 0.05) / (L2 + 0.05)` where L1 is the lighter color's luminance. Pure white has luminance 1.0, pure black has luminance 0.0. This means `#767676` on `#ffffff` produces exactly 4.54:1 — the minimum AA threshold for normal text. This is the lightest gray you can use for body text on white.
+
+3. **Design contrast tiers, not just minimum compliance.** Contrast is a hierarchy tool. Apple's approach demonstrates three distinct tiers:
+   - **Primary content** (headings, primary labels): 15:1 to 21:1 — near-black on white (`#1D1D1F` on `#FFFFFF` = 17.4:1)
+   - **Secondary content** (subheadings, secondary labels): 7:1 to 10:1 — dark gray (`#424245` on `#FFFFFF` = 9.6:1)
+   - **Tertiary content** (timestamps, metadata, captions): 4.5:1 to 7:1 — medium gray (`#6E6E73` on `#FFFFFF` = 5.5:1)
+   - **Decorative/disabled**: below 4.5:1 — light gray for non-essential elements
+
+   This graduated system creates clear visual hierarchy through contrast alone, without relying on font size or weight changes.
+
+4. **Apply the squint test.** Squint at your interface until details blur. The elements that remain visible have high contrast and will be read first. If your primary CTA disappears when squinting but a decorative element persists, your contrast hierarchy is inverted.
+
+5. **Calculate, do not eyeball.** Human contrast perception is unreliable — we are biased by surrounding colors, screen brightness, and ambient light. Always use a tool:
+   - Browser DevTools color picker (shows contrast ratio on hover)
+   - WebAIM Contrast Checker (webaim.org/resources/contrastchecker)
+   - Figma plugins: Stark, A11y - Color Contrast Checker
+   - CLI: `npx wcag-contrast <fg> <bg>` for automation in CI
+
+6. **Check all interactive states.** A button that passes contrast in its default state may fail in hover, focus, active, or disabled states. Audit every state:
+   - Default: must meet 3:1 for the component boundary and 4.5:1 for text
+   - Hover: contrast may shift — verify it does not drop below thresholds
+   - Focus: focus indicator must have 3:1 against adjacent colors (WCAG 2.4.11)
+   - Disabled: exempt from contrast requirements, but should still be perceivable as present (not invisible)
+
+7. **Handle text on images and gradients.** Text placed over photography or gradients will have variable contrast across its length. Solutions:
+   - Add a semi-transparent overlay: `rgba(0, 0, 0, 0.6)` behind white text guarantees 4.5:1+ against any background
+   - Use a solid pill or banner behind the text
+   - Stripe uses blue-tinted shadow overlays (`rgba(50, 50, 93, 0.25)`) that maintain chromatic depth while ensuring contrast for overlaid text
+
+8. **Use contrast to encode importance, not just ensure readability.** Higher contrast elements receive more visual attention. Stripe's dashboard hierarchy:
+   - Transaction amounts: `#061b31` on white (18.5:1) — maximum emphasis
+   - Status labels: `#425466` on white (7.3:1) — secondary emphasis
+   - Timestamps: `#697386` on white (4.9:1) — tertiary, just above AA minimum
+   - Decorative dividers: `#e3e8ee` on white (1.6:1) — structural, not meant to be "read"
+
+## Details
+
+### The Luminance Scale Is Not Linear
+
+A common mistake is assuming that moving from `#000` to `#808080` (visual midpoint) is "half" the contrast range. It is not. `#808080` on white yields only 3.9:1, while `#808080` on black yields 5.3:1. The luminance formula applies gamma correction (sRGB transfer function), which compresses the dark end and expands the light end. This is why dark themes need different contrast calibration than light themes — the perceptual spacing between dark grays is narrower than between light grays.
+
+### Contrast in Dark Mode
+
+Dark mode does not mean "invert the contrast ratios." It means recalibrating the entire contrast scale against a dark base. Key differences:
+
+- **Maximum contrast is harmful.** Pure white (`#FFFFFF`) on pure black (`#000000`) is 21:1 — technically perfect but physiologically exhausting for sustained reading. Material Design recommends capping dark mode text contrast at approximately 15.8:1 by using `#E3E3E3` (87% opacity white) on `#121212` instead of pure white on pure black.
+- **Elevation through contrast.** In dark mode, higher surfaces are lighter. Material Design 3 uses: base surface `#1C1B1F`, elevated surfaces at `#211F26`, `#2B2930`, `#322F37`, `#393542` — each step increasing lightness by 1-3% to create depth through subtle contrast shifts.
+- **Colored text needs extra care.** Saturated colors that pass on white may fail on dark backgrounds. Stripe's purple `#533afd` passes on white (5.6:1) but would need to lighten to approximately `#7B6BFF` to maintain 4.5:1 on `#121212`.
+
+### Contrast Zones Framework
+
+Organize your design system's contrast into explicit zones:
+
+| Zone           | Ratio Range | Purpose                               | Examples                                  |
+| -------------- | ----------- | ------------------------------------- | ----------------------------------------- |
+| **Maximum**    | 12:1 - 21:1 | Primary content, critical information | Headings, prices, error messages          |
+| **High**       | 7:1 - 12:1  | Important secondary content           | Subheadings, button labels, input text    |
+| **Standard**   | 4.5:1 - 7:1 | Supporting content                    | Body text, descriptions, secondary labels |
+| **Minimum**    | 3:1 - 4.5:1 | Non-critical UI, large text           | Placeholder text, icons, borders          |
+| **Decorative** | Below 3:1   | Non-informational                     | Dividers, watermarks, background patterns |
+
+Assign every text and UI element to a zone. If two elements in different zones look the same contrast, one of them is in the wrong zone.
+
+### Anti-Patterns
+
+1. **Gray-on-Gray Elegance.** Mistaking low contrast for sophistication. Symptoms: body text at 3.5:1, placeholder text at 2:1, borders invisible on their backgrounds. Many "minimalist" design portfolios fail AA entirely. Sophistication comes from contrast _hierarchy_ (having distinct tiers), not contrast _reduction_ (making everything low-contrast). Stripe is sophisticated AND high-contrast — headings at 18.5:1, body at 7.3:1.
+
+2. **Contrast Overload.** Everything at maximum contrast (near 21:1) destroys hierarchy because nothing stands out more than anything else. If all text is pure black on pure white, you have lost your most powerful hierarchy tool. Fix: reserve maximum contrast for a single tier (headings or primary actions) and deliberately reduce contrast for secondary and tertiary content.
+
+3. **Ignoring Non-Text Contrast.** WCAG 2.1 SC 1.4.11 requires 3:1 for UI components — but many implementations only check text. A light gray checkbox border (`#D0D0D0` on `#FFFFFF` = 1.5:1) is invisible to low-vision users even if the label text passes. Form input borders, toggle switches, slider tracks, and icon buttons all need 3:1 verification.
+
+4. **Focus Indicator Failure.** The default browser focus outline is often overridden with `outline: none` for aesthetics, then replaced with a custom focus ring that fails contrast. A blue focus ring (`#5B9BD5`) on a white background is only 2.8:1. Apple uses a thick (3px) blue ring (`#007AFF` on white = 4.0:1) with an additional white inner offset to guarantee visibility against any adjacent color.
+
+5. **Contrast Tunnel Vision.** Checking contrast only in isolation (swatch-to-swatch) instead of in context. A text color that passes against its immediate background may be imperceptible if the surrounding elements have higher contrast, drawing the eye away. Always verify contrast in a full-page context, not just in a color-picker tool.
+
+### Real-World Examples
+
+**Apple — Three-Tier Hierarchy.** Apple's Human Interface Guidelines use a precise three-tier contrast system across all platforms. On a white background: primary labels use `#000000` (21:1), secondary labels use `rgba(60, 60, 67, 0.6)` (~7.2:1), and tertiary labels use `rgba(60, 60, 67, 0.3)` (~3.5:1, acceptable only for large or non-critical text). In dark mode, these invert to white at 100%/60%/30% opacity on the dark surface. The ratios shift but the relative hierarchy is preserved.
+
+**Material Design — Opacity-Based Contrast.** Material Design maps contrast to opacity rather than fixed colors. On a light surface, high-emphasis text is `rgba(0,0,0,0.87)` (12.6:1), medium-emphasis is `rgba(0,0,0,0.60)` (7.1:1), and disabled text is `rgba(0,0,0,0.38)` (3.5:1). This approach ensures that contrast tiers automatically adjust when the surface color changes — the system is self-calibrating.
+
+**Vercel — Numeric Contrast Scale.** Vercel's Geist design system defines a numeric gray scale (gray-100 through gray-1000) where each step is explicitly mapped to a contrast role. Gray-900 (`#171717`) is for headings (18.9:1 on white), gray-700 (`#404040`) for body text (9.7:1), gray-500 (`#737373`) for secondary text (4.6:1), and gray-300 (`#D4D4D4`) for borders (1.5:1, decorative only). The scale makes contrast auditing mechanical — check the gray number, know the contrast zone.
+
+**Stripe — Chromatic Contrast.** Stripe extends contrast thinking beyond achromatic grays. Their shadows use `rgba(50, 50, 93, 0.25)` — a blue-tinted shadow that creates visual depth while maintaining chromatic coherence with the navy headings. The contrast between the shadow and the card surface is deliberately low (decorative zone), but the shadow's blue tint ensures it registers as intentional design rather than a rendering artifact.
+
+### Contrast and Typography Interaction
+
+Contrast requirements interact with font weight and size. A font rendered at weight 300 (light) appears lower-contrast than the same color at weight 700 (bold), even though the calculated ratio is identical — because thinner strokes occupy fewer pixels, reducing effective contrast. Stripe uses weight 300 for its display typography as a luxury signal, but compensates by using very high contrast colors (`#061b31` on white = 18.5:1). If you use light font weights, increase your target contrast ratio by at least one tier above the WCAG minimum.
+
+## Source
+
+- WCAG 2.1 Success Criterion 1.4.3 — Contrast (Minimum) — https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum
+- WCAG 2.1 Success Criterion 1.4.6 — Contrast (Enhanced)
+- WCAG 2.1 Success Criterion 1.4.11 — Non-text Contrast
+- W3C Relative Luminance Definition — https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+- Material Design — Dark Theme Guidelines — https://m3.material.io/styles/color/dark-theme
+
+## Process
+
+1. Read the contrast zone framework and map your design system's elements to zones (maximum, high, standard, minimum, decorative).
+2. Assign specific contrast ratios to each element by zone, using the WCAG thresholds as minimums and the tiered approach for hierarchy.
+3. Verify every text element, UI component, and interactive state with a contrast checking tool. Confirm that the hierarchy is perceptible via the squint test.
+4. Re-check contrast ratios after any color change — a single hex value shift can drop an element below threshold.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+- **Pairs with:** design-color-harmony (contrast must not undermine harmony choices), design-color-accessibility (contrast is necessary but not sufficient for accessibility), design-visual-hierarchy (contrast is the primary mechanism for visual hierarchy), a11y-color-contrast (implementation-level contrast patterns in code).
+- **Sequencing:** Apply after design-color-harmony has established the palette. Contrast verification is a gate — no color choice is final until contrast is verified.
+
+## Success Criteria
+
+- Every text element meets its WCAG tier: 4.5:1 for normal text (AA), 3:1 for large text (AA), 7:1 for enhanced (AAA).
+- Non-text UI components (borders, icons, form controls) meet 3:1 against adjacent colors.
+- The design uses at least 3 distinct contrast tiers (not a flat single-tier approach).
+- The squint test confirms that the visual hierarchy matches the intended information hierarchy.
+- All interactive states (hover, focus, active, disabled) have been verified for contrast.
+- Dark mode contrast ratios have been independently verified (not assumed from light mode).
+- Contrast values are documented in the design system (not embedded as magic numbers in components).
+- Focus indicators meet 3:1 against adjacent colors per WCAG 2.4.11.
+- Light font weights (300-400) use contrast ratios at least one tier above the WCAG minimum to compensate for reduced stroke density.

package/dist/agents/skills/claude-code/design-contrast-ratio/skill.yaml

@@ -0,0 +1,35 @@
+name: design-contrast-ratio
+version: "1.0.0"
+description: Luminance contrast for readability and visual weight — WCAG ratios, contrast as hierarchy tool
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-color-harmony
+  - design-color-accessibility
+  - a11y-color-contrast
+  - design-visual-hierarchy
+stack_signals: []
+keywords:
+  - contrast ratio
+  - luminance
+  - WCAG
+  - readability
+  - visual weight
+  - AA
+  - AAA
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []