@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/gemini-cli/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/gemini-cli/design-content-density/skill.yaml

@@ -0,0 +1,35 @@
+name: design-content-density
+version: "1.0.0"
+description: Information density tradeoffs — compact vs. comfortable vs. spacious, data-dense vs. marketing
+stability: static
+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/gemini-cli/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/gemini-cli/design-contrast-ratio/skill.yaml

@@ -0,0 +1,36 @@
+name: design-contrast-ratio
+version: "1.0.0"
+description: Luminance contrast for readability and visual weight — WCAG ratios, contrast as hierarchy tool
+stability: static
+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: []

package/dist/agents/skills/gemini-cli/design-dark-mode-color/SKILL.md

@@ -0,0 +1,152 @@
+# Dark Mode Color
+
+> Color adaptation for dark themes — inverted hierarchy, reduced saturation, elevation through lightness, surface layering, and maintaining brand identity in dark contexts
+
+## When to Use
+
+- Building a dark theme for an existing light-mode product
+- Designing a product that launches in dark mode by default (media players, code editors, creative tools)
+- Adapting a light-mode color palette to dark surfaces without losing brand recognition
+- Creating elevated surface layers in dark UI (cards, modals, popovers, dropdowns)
+- Choosing text colors and opacities for dark backgrounds
+- Debugging dark mode issues: eye strain, halation, invisible borders, lost hierarchy
+- Implementing `prefers-color-scheme` CSS media query with design-informed token mapping
+- Building a design system that supports both themes with shared component architecture
+
+## Instructions
+
+1. **Dark mode is not "invert colors."** The fundamental error is thinking dark mode means swapping black and white. It means rebuilding the entire visual hierarchy for dark surfaces. Key inversions:
+   - **Light mode:** Elevation = shadow (darker beneath). **Dark mode:** Elevation = lighter surface (higher = lighter).
+   - **Light mode:** Background is lightest, text is darkest. **Dark mode:** Background is darkest, but text should NOT be pure white.
+   - **Light mode:** Saturated colors pop against white. **Dark mode:** Same saturated colors cause halation (glow/bleed) against dark backgrounds and must be desaturated.
+
+2. **Never use pure black (`#000000`) as the base surface.** Pure black creates maximum contrast (21:1) against white text, causing eye fatigue during extended reading. It also makes the screen look like a "hole" — the content floats in void rather than sitting on a surface. Use dark gray instead:
+   - **Material Design 3:** `#1C1B1F` (slightly warm purple-tinted dark gray)
+   - **GitHub:** `#0d1117` (blue-tinted near-black)
+   - **Spotify:** `#121212` (near-neutral dark gray)
+   - **Apple:** `#000000` for OLED true black mode (power saving exception), `#1C1C1E` for standard dark mode
+
+   Decision procedure: use `#121212` or darker as your base surface. Tint it toward your brand hue at very low saturation (2-5%) for chromatic unity. Exception: OLED-specific modes may use `#000000` for power efficiency, but this should be an opt-in mode, not the default.
+
+3. **Build surface elevation through lightness, not shadows.** In dark mode, shadows are invisible (dark on dark). Replace the shadow-based elevation system with a lightness-based one:
+
+   | Elevation Level | Light Mode                 | Dark Mode (MD3)          | Purpose                               |
+   | --------------- | -------------------------- | ------------------------ | ------------------------------------- |
+   | Level 0 (base)  | `#FFFFFF`                  | `#1C1B1F`                | Page background                       |
+   | Level 1         | `#FFFFFF` + shadow         | `#211F26` (+3% lighter)  | Cards, raised sections                |
+   | Level 2         | `#FFFFFF` + deeper shadow  | `#2B2930` (+6% lighter)  | Navigation drawers, modal backgrounds |
+   | Level 3         | `#FFFFFF` + heavy shadow   | `#322F37` (+8% lighter)  | Floating action buttons, search bars  |
+   | Level 4         | `#FFFFFF` + maximum shadow | `#393542` (+11% lighter) | Popovers, dropdown menus, tooltips    |
+
+   Material Design 3 adds a surface tint: overlay the primary color at low opacity (5-14%) on each surface level. This creates chromatic elevation — higher surfaces are not just lighter, they are slightly more tinted toward the brand color, reinforcing the connection between elevation and brand identity.
+
+4. **Reduce saturation for chromatic colors on dark backgrounds.** Vivid colors on dark surfaces produce halation — a perceived glow around the color boundary caused by the eye's inability to focus all wavelengths at the same depth. The effect is strongest with warm, saturated colors (red, orange).
+
+   **Desaturation guidelines:**
+   - Primary brand colors: reduce saturation by 10-20% from light mode values, or increase lightness by 15-25%
+   - Apple adapts system colors: `systemBlue` shifts from `#007AFF` (light) to `#0A84FF` (dark) — the dark variant is lighter (L+5%) and very slightly desaturated
+   - Stripe's `#533afd` would need to lighten to approximately `#7B6BFF` for dark mode to maintain contrast while reducing halation
+   - Semantic colors: error red shifts from `#EF4444` to `#FCA5A5` (lighter, less saturated); success green from `#22C55E` to `#86EFAC`
+
+5. **Set text opacity tiers, not fixed text colors.** Using opacity-based text creates a self-calibrating system — when the surface color changes across elevation levels, the text contrast adjusts automatically:
+
+   | Text Role                          | Light Mode         | Dark Mode                | Contrast on #121212 |
+   | ---------------------------------- | ------------------ | ------------------------ | ------------------- |
+   | Primary (headings, body)           | `rgba(0,0,0,0.87)` | `rgba(255,255,255,0.87)` | ~15.8:1             |
+   | Secondary (descriptions, metadata) | `rgba(0,0,0,0.60)` | `rgba(255,255,255,0.60)` | ~9.1:1              |
+   | Disabled / Placeholder             | `rgba(0,0,0,0.38)` | `rgba(255,255,255,0.38)` | ~4.7:1              |
+
+   Material Design established these tiers. The 87%/60%/38% ratios ensure that primary text exceeds 7:1 (AAA), secondary exceeds 4.5:1 (AA), and disabled hovers just above 4.5:1 — providing hierarchy through contrast while meeting accessibility requirements at each tier.
+
+6. **Maintain brand recognition across themes.** The brand should be instantly recognizable in dark mode. Strategies:
+   - **Preserve hue, adapt lightness:** Keep the same hue and similar saturation, but shift lightness up for readability. Stripe's purple shifts from 500-equivalent in light mode to 300-400 equivalent in dark mode.
+   - **Preserve the logo/brand mark:** Use the light variant of the logo on dark backgrounds, not the dark variant.
+   - **Preserve structural hierarchy:** If navy text was the primary structural color in light mode, the equivalent in dark mode is a light blue-gray that carries the same hue family.
+
+7. **Handle images and media.** Full-brightness images on a dark surface create jarring contrast. Solutions:
+   - Reduce image brightness by 10-15% in dark mode: `filter: brightness(0.85)`
+   - Add a subtle dark overlay on hero images
+   - Use image frames (subtle borders or rounded containers with dark surface backgrounds) to mediate the transition
+   - GitHub uses `border: 1px solid rgba(255,255,255,0.1)` around images in dark mode to separate image content from the dark background
+
+## Details
+
+### The Halation Problem
+
+Halation occurs when bright, saturated colors are displayed on very dark backgrounds. The eye's lens cannot focus all wavelengths at the same point (chromatic aberration), causing colored text or elements to appear to glow, bleed, or vibrate. The effect is worst for:
+
+- **Red and orange text on black** — long wavelengths focus behind the retina on dark backgrounds
+- **High-saturation blues** — short wavelengths focus in front of the retina
+- **Any saturated color at small text sizes** — thin strokes make the glow more apparent relative to letter width
+
+Fix: desaturate colors by 15-30% for dark mode use, or increase lightness to shift toward pastel territory. Apple's dark mode color adaptations demonstrate this: every system color shifts lighter and slightly less saturated in dark mode. `systemRed` goes from `#FF3B30` to `#FF453A` — subtle but measurable.
+
+### Dark Mode Surface Token Architecture
+
+A robust dark mode implementation uses semantic surface tokens, not hard-coded colors:
+
+```
+--surface-base:    #121212   /* Page background */
+--surface-raised:  #1E1E1E   /* Cards, sections */
+--surface-overlay: #2C2C2C   /* Modals, popovers */
+--surface-highest: #383838   /* Tooltips, dropdowns */
+--on-surface:      rgba(255,255,255,0.87)  /* Primary text */
+--on-surface-secondary: rgba(255,255,255,0.60)  /* Secondary text */
+--on-surface-disabled:  rgba(255,255,255,0.38)  /* Disabled text */
+```
+
+These tokens swap between themes while component code remains unchanged. The `on-surface` naming convention (from Material Design) makes the relationship explicit: `--on-surface` is always readable on `--surface-base`.
+
+### Anti-Patterns
+
+1. **Pure Black Background.** Using `#000000` as the default dark surface. Symptoms: the UI feels like a void, text creates harsh contrast that causes eye fatigue, elevated surfaces require enormous lightness jumps to be distinguishable. OLED power saving is not a sufficient justification for default pure black — even Samsung's One UI uses `#1A1A1A`, not `#000000`. Fix: use `#121212` to `#1C1B1F` as your dark surface base.
+
+2. **Direct Palette Inversion.** Taking the light mode palette and mechanically inverting it (white becomes black, light gray becomes dark gray). Symptoms: brand colors look wrong, the hierarchy feels off, saturated elements glow uncomfortably. Fix: rebuild the dark palette from the same brand hue but with dark-mode-specific lightness, saturation, and contrast calibration. Light-300 does not become Dark-700 — the relationship is more nuanced than simple number inversion.
+
+3. **Shadow Dependence.** Keeping `box-shadow` as the primary elevation mechanism in dark mode. Symptoms: cards are flat (shadows invisible against dark backgrounds), the UI loses all depth perception, modal overlays do not feel elevated. Fix: replace shadows with surface lightness tiers and/or subtle borders. Material Design 3 uses both surface tint and a 1px hairline border (`rgba(255,255,255,0.05)`) for dark mode elevation.
+
+4. **Maximum Contrast Text.** Using pure white `#FFFFFF` text on the dark surface. Symptoms: eye fatigue after extended reading, text appears to "shimmer" or strobe on high-DPI screens, the overall feel is clinical and harsh. Fix: use `rgba(255,255,255,0.87)` or `#E0E0E0` for primary text, reserving pure white only for the most critical, short-form content (page titles, modal headers).
+
+5. **Forgetting Borders.** Relying on background contrast to separate adjacent components that were separated by shadows in light mode. In dark mode, two adjacent cards at the same surface level are indistinguishable. Fix: add 1px borders using `rgba(255,255,255,0.08-0.12)` between same-level surfaces. GitHub's dark mode uses this extensively — every card, comment box, and code block has a subtle light border.
+
+### Real-World Examples
+
+**Material Design 3 — Surface Tint System.** MD3's dark mode overlays the primary color at escalating opacities on each surface level: Level 1 = primary at 5%, Level 2 = 8%, Level 3 = 11%, Level 4 = 12%, Level 5 = 14%. On a base of `#1C1B1F` with primary `#D0BCFF`, Level 1 becomes a barely-perceptible warm purple tint. This creates a hierarchy that is both functional (elevated surfaces are lighter) and branded (the elevation is tinted with the product color).
+
+**Apple — Semantic Color Adaptation.** Apple's system colors are not single values — they are dynamic. Each system color has four variants: light mode default, light mode accessible (higher contrast), dark mode default, and dark mode accessible. `systemBlue` in dark mode is `#0A84FF` — 7% lighter and 2% more saturated than light mode's `#007AFF`. This shift is calibrated per-color: red shifts more in lightness, green shifts less, because each hue has different perceptual behavior on dark backgrounds.
+
+**GitHub — Primer Dark Palette.** GitHub's Primer design system defines a complete dark mode palette with 10 levels of gray from `#0d1117` (canvas default) through `#f0f6fc` (fg default). The palette maintains a cool blue undertone in dark mode (matching their brand), and every surface level has explicit named tokens: `canvas.default`, `canvas.overlay`, `canvas.inset`, `canvas.subtle`. Border tokens shift from shadow-based separation in light mode to 1px borders at `rgba(240,246,252,0.1)` in dark mode.
+
+## Source
+
+- Material Design 3 Dark Theme — https://m3.material.io/styles/color/dark-theme
+- Apple Human Interface Guidelines — Dark Mode — https://developer.apple.com/design/human-interface-guidelines/dark-mode
+- GitHub Primer Color System — https://primer.style/design/foundations/color
+- WCAG 2.1 — Contrast requirements apply equally in dark mode
+
+## Process
+
+1. Start from your light-mode palette (from design-palette-construction). Identify the base surface color (use `#121212` to `#1C1B1F`, optionally tinted toward brand hue).
+2. Build 4-5 surface elevation levels by incrementally lightening the base. Optionally apply primary color tint at 5-14% per Material Design 3.
+3. Adapt all chromatic colors: reduce saturation 10-20%, increase lightness 15-25%. Set text opacity tiers at 87%/60%/38%.
+4. Test the complete dark palette in a component matrix. Verify contrast at each elevation level. Check for halation with saturated colors at small text sizes.
+
+## 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-palette-construction (dark mode is a derivative of the base palette), design-contrast-ratio (all contrast requirements apply equally in dark mode), design-elevation-shadow (dark mode replaces shadow-based elevation with lightness-based elevation), css-dark-mode (implementation patterns for `prefers-color-scheme`).
+- **Sequencing:** Use after design-palette-construction. Dark mode adaptation is a separate step from palette construction, not an afterthought.
+
+## Success Criteria
+
+- The dark surface base is not pure black — it uses `#121212` or warmer with optional brand tint.
+- At least 4 surface elevation levels are defined with progressive lightness increases.
+- All chromatic colors have dark-mode-specific values with reduced saturation and increased lightness.
+- Text uses opacity-based tiers (87%/60%/38%) that self-calibrate across surface levels.
+- No halation is visible with saturated colors at body text sizes on the dark surface.
+- Shadows are replaced with surface lightness and/or subtle borders for elevation.
+- Brand identity is recognizable — hue is preserved even as lightness and saturation shift.
+- All WCAG contrast requirements are met independently in dark mode (not inherited from light mode).
+- Images and media are handled with brightness reduction or border framing to avoid jarring contrast.
+- The dark palette is implemented through semantic tokens that swap between themes.

package/dist/agents/skills/gemini-cli/design-dark-mode-color/skill.yaml

@@ -0,0 +1,36 @@
+name: design-dark-mode-color
+version: "1.0.0"
+description: Color adaptation for dark themes — inverted hierarchy, reduced saturation, elevation through lightness
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-palette-construction
+  - design-elevation-shadow
+  - design-contrast-ratio
+  - css-dark-mode
+stack_signals: []
+keywords:
+  - dark mode
+  - dark theme
+  - inverted hierarchy
+  - reduced saturation
+  - elevation
+  - surface tint
+  - night mode
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []