@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/codex/design-gestalt-similarity/skill.yaml

@@ -0,0 +1,33 @@
+name: design-gestalt-similarity
+version: "1.0.0"
+description: Visual kinship — elements sharing color, size, shape, or texture perceived as related, creating categories without explicit labels
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-gestalt-proximity
+  - design-consistency
+  - design-visual-hierarchy
+stack_signals: []
+keywords:
+  - gestalt
+  - similarity
+  - visual-kinship
+  - color-grouping
+  - shape-grouping
+  - categorization
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-grid-systems/SKILL.md

@@ -0,0 +1,154 @@
+# Grid Systems
+
+> Grid theory — column, modular, baseline, and compound grids, gutter rhythm, and breaking the grid intentionally for emphasis
+
+## When to Use
+
+- Laying out any page or screen with more than a single column of content
+- Establishing consistent horizontal and vertical rhythm across a product
+- Deciding column counts, gutter widths, and margin sizes for a new design system
+- Evaluating whether an existing layout feels disorganized or inconsistent
+- Planning responsive layouts that reflow predictably across breakpoints
+
+## Instructions
+
+1. **Choose a grid type based on content structure.** There are five fundamental grid types — each solves a different layout problem:
+   - **Manuscript grid** — Single column, maximum reading width. Use for long-form articles, documentation, legal text. Apple's developer documentation uses a manuscript grid with a fixed sidebar: content column maxes out at ~680px to maintain a 60-75 character line length.
+   - **Column grid** — 2-12 vertical columns with gutters. The workhorse of web layout. Use for dashboards, marketing pages, product listings. Material Design 3 specifies 4 columns on compact (<600dp), 8 on medium (600-839dp), and 12 on expanded (840dp+).
+   - **Modular grid** — Column grid plus horizontal divisions creating a matrix of cells. Use for image galleries, card layouts, calendars. Pinterest's masonry layout is a modular grid variant where row heights flex.
+   - **Baseline grid** — Invisible horizontal lines at regular intervals (typically 4px or 8px) that text and elements snap to. Ensures vertical rhythm. Stripe uses an 8px baseline: all padding, margin, and line-height values are multiples of 8 (8, 16, 24, 32, 48, 64).
+   - **Compound grid** — Two or more grids overlaid. Use for complex editorial layouts where different content zones need different column counts. The New York Times web edition overlays a 4-column news grid on a 3-column sidebar grid.
+
+2. **Set column count by content needs, not convention.** The 12-column grid is popular because 12 divides evenly by 2, 3, 4, and 6 — but it is not always correct:
+   - **4 columns** — Mobile layouts, simple forms, single-focus pages
+   - **6 columns** — Tablet layouts, medium-complexity dashboards
+   - **8 columns** — Wide tablets, secondary desktop views
+   - **12 columns** — Full desktop layouts with complex content arrangements
+   - **16 columns** — Data-heavy enterprise applications (Bloomberg Terminal, Figma's property panels)
+
+   Material Design's responsive grid uses 4/8/12 at breakpoints 600dp and 840dp. Stripe's marketing pages use 12 columns but constrain content to the inner 8, creating generous margins.
+
+3. **Size gutters proportionally.** Gutters (the space between columns) control density and readability:
+   - **16px gutters** — Compact layouts, data tables, dashboards (Material Design compact)
+   - **20px gutters** — Standard density, most web applications
+   - **24px gutters** — Comfortable layouts, content-rich pages (Airbnb uses 24px gutters in its card grid)
+   - **32px gutters** — Spacious layouts, marketing pages, premium feel
+   - **Rule of thumb:** Gutter width should be 1/3 to 1/2 of column width. If columns are 72px wide, gutters of 24-36px feel proportional.
+
+4. **Set margins to frame the content.** Margins are the space between the grid and the viewport edge:
+   - **Mobile:** 16-24px margins (Material Design uses 16px on compact)
+   - **Tablet:** 24-32px margins
+   - **Desktop:** 32-80px margins, or use a max-width container. Stripe caps content at ~1080px with auto margins, creating a centered content well on wide screens. Vercel uses ~1200px max-width.
+   - **Proportional margins:** Some systems scale margins with viewport — 5% on mobile, 10% on desktop.
+
+5. **Establish a baseline grid for vertical rhythm.** Every vertical measurement should be a multiple of a base unit:
+   - **4px base** — Fine-grained control, good for dense UIs. Used by Spotify for tight spacing in playlist views.
+   - **8px base** — The industry standard. Stripe, Material Design, and Shopify Polaris all use 8px. Spacing scale: 8, 16, 24, 32, 48, 64, 96, 128.
+   - **Line-height alignment:** Body text line-height should be a multiple of the base unit. 16px text at 1.5 line-height = 24px = 3 x 8px base. This keeps text aligned to the grid.
+
+6. **Break the grid intentionally for emphasis.** A grid break works because it violates an established pattern — the viewer notices the violation. This only works if the grid is otherwise consistent:
+   - **Full-bleed images** — Extend past grid margins to the viewport edge. Vercel uses full-bleed dark sections to separate content zones on its homepage.
+   - **Breakout elements** — Span more columns than surrounding content. A pull quote spanning 8 columns in a 6-column content area creates emphasis.
+   - **Offset placement** — Shift an element off the grid by a deliberate amount. Apple's product pages offset hero images to create dynamic asymmetry.
+   - **Rule:** Break one axis at a time. If an element breaks the column grid, it should still respect the baseline grid.
+
+## Details
+
+### Grid Anatomy Reference
+
+| Component | Definition                       | Typical Values                |
+| --------- | -------------------------------- | ----------------------------- |
+| Column    | Vertical content container       | 60-120px width at desktop     |
+| Gutter    | Space between columns            | 16-32px                       |
+| Margin    | Space between grid and viewport  | 16-80px                       |
+| Field     | Modular grid horizontal division | Height based on baseline unit |
+| Flowline  | Horizontal alignment line        | Aligns to baseline grid       |
+
+### Anti-Patterns
+
+1. **Gutterless grids.** Columns with no space between them cause content collision. Text from one column bleeds visually into the next. Even a minimal 8px gutter provides enough separation. If you see content that feels "cramped," the first diagnosis is missing or insufficient gutters.
+
+2. **Inconsistent margins.** Left margin at 20px, right at 32px — this is not a design system, it is a mistake. Margins must be symmetric (or intentionally asymmetric for a specific purpose like a fixed sidebar). Stripe's symmetric margins create a centered, balanced frame.
+
+3. **The 12-column trap.** Defaulting to 12 columns for everything, even when the layout only needs 2-3 content zones. A simple landing page with a hero, features section, and footer needs at most a 3-4 column grid. Using 12 columns adds complexity with no benefit and makes responsive behavior harder to manage.
+
+4. **Ignoring the baseline.** Vertical spacing that uses arbitrary values (13px, 27px, 41px) instead of baseline multiples. This destroys vertical rhythm — elements feel randomly placed even if they are technically aligned horizontally. Audit by checking: is every vertical spacing value a multiple of 4 or 8?
+
+### Choosing a Grid: Decision Procedure
+
+Use this flowchart to select the right grid type for any project:
+
+1. Is the content primarily long-form text? **Manuscript grid** — single column, 60-75 characters wide.
+2. Is the content a collection of similar items (cards, products, images)? **Modular grid** — equal cells with consistent aspect ratios.
+3. Is the content mixed (text blocks, images, CTAs, data) with 2+ distinct zones? **Column grid** — assign different column spans to each zone.
+4. Do you need multiple independent layout zones on the same page (e.g., editorial sidebar + news feed + ad rail)? **Compound grid** — overlay two column grids with different column counts.
+5. In ALL cases, add a **baseline grid** underneath. The baseline grid is not an alternative to other types — it is a vertical rhythm layer that combines with any horizontal grid.
+
+### Grid Math
+
+For a 12-column grid inside a 1200px container with 24px gutters:
+
+- Total gutter space: 11 gutters x 24px = 264px
+- Remaining for columns: 1200px - 264px = 936px
+- Column width: 936px / 12 = 78px
+- A 4-column span: (4 x 78px) + (3 x 24px) = 384px
+- A 6-column span: (6 x 78px) + (5 x 24px) = 588px
+
+This math matters when setting max-widths, image sizes, and component widths. Hard-coding pixel values without understanding the underlying grid math leads to layouts that break at different container sizes.
+
+### Real-World Examples
+
+**Material Design 3 Responsive Grid:**
+
+- Compact (0-599dp): 4 columns, 16px gutters, 16px margins
+- Medium (600-839dp): 8 columns, 24px gutters, 24px margins
+- Expanded (840dp+): 12 columns, 24px gutters, 24px margins
+- Layout regions use column spans: navigation (3-4 cols), content (6-8 cols), supporting (2-3 cols)
+- Body regions classified as: navigation, body (primary + secondary), supporting pane
+
+**Stripe Marketing Pages:**
+
+- 12-column grid at 1080px max-width with 20px gutters
+- Content constrained to inner 8 columns (leaving 2 margin columns each side)
+- Section padding: 96px (12 x 8px base unit) between major sections
+- Full-bleed dark/light section alternation breaks the column grid while maintaining vertical rhythm
+- Code examples use a 6-column span; descriptive text uses the adjacent 4-column span
+
+**Airbnb Card Grid:**
+
+- Responsive card count: 1 card (<550px), 2 cards (550-949px), 3 cards (950-1127px), 4 cards (1128px+)
+- Consistent 24px gutters between cards at all breakpoints
+- Cards maintain a fixed aspect ratio; only count changes across breakpoints
+- Search results page: map occupies 5 columns of a 12-column grid; listings occupy 7
+
+**Apple Developer Documentation:**
+
+- Manuscript grid with 260px fixed sidebar on desktop
+- Content column capped at ~680px for optimal line length
+- Sidebar collapses to hamburger menu below 1024px — a responsive grid adaptation
+- 4px baseline grid for tight vertical alignment of code blocks and body text
+
+## Source
+
+- Josef Muller-Brockmann, "Grid Systems in Graphic Design" — the foundational text on systematic grid use
+- Massimo Vignelli, "The Vignelli Canon" — practical grid application in identity and editorial design
+- Material Design 3 layout documentation (m3.material.io/foundations/layout)
+- Karl Gerstner, "Designing Programmes" — compound grid theory and systematic design
+
+## Process
+
+1. **Identify** content types and their structural needs (text columns, card grids, data tables)
+2. **Select** grid type and parameters (column count, gutter width, baseline unit, margins)
+3. **Validate** by checking that all spacing values are multiples of the base unit and that the grid supports all required layout variations
+
+## Harness Integration
+
+This is a knowledge skill. When activated, its content is injected into the system prompt to guide layout decisions. It does not execute code or modify files. Use alongside `design-alignment` for element placement, `design-whitespace` for spacing decisions, and `design-responsive-strategy` for breakpoint behavior.
+
+## Success Criteria
+
+- Layout uses a named grid type (column, modular, baseline, compound) with explicit parameters
+- All gutter and margin values are consistent and proportional to column width
+- Vertical spacing uses multiples of a declared base unit (4px or 8px)
+- Grid breaks are intentional and limited to 1-2 per page for emphasis
+- Responsive behavior changes column count at defined breakpoints, not arbitrary widths

package/dist/agents/skills/codex/design-grid-systems/skill.yaml

@@ -0,0 +1,35 @@
+name: design-grid-systems
+version: "1.0.0"
+description: Grid theory — column, modular, baseline, compound grids, breaking the grid intentionally
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-alignment
+  - design-whitespace
+  - design-responsive-strategy
+stack_signals: []
+keywords:
+  - grid
+  - column grid
+  - modular grid
+  - baseline grid
+  - gutter
+  - margin
+  - grid breakout
+  - layout grid
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-i18n-design/SKILL.md

@@ -0,0 +1,181 @@
+# Internationalization Design
+
+> Designing for internationalization — text expansion, RTL layout, icon cultural sensitivity, date/number/currency formatting, pseudolocalization testing
+
+## When to Use
+
+- Building a new product or feature that will launch in multiple languages or markets
+- Retrofitting an English-first product for international audiences
+- Reviewing a design for text expansion issues before localization begins
+- Designing a layout that must support both LTR (English, French) and RTL (Arabic, Hebrew) scripts
+- Choosing icons, imagery, or color that will appear in culturally diverse markets
+- Implementing date, time, number, or currency formatting that varies by locale
+- Setting up pseudolocalization to catch i18n bugs before real translations arrive
+- Evaluating whether a design system's components are i18n-ready
+- Designing forms that accept international names, addresses, and phone numbers
+
+## Instructions
+
+1. **Design for text expansion from the start.** English is one of the most compact major languages. When translated, text expands significantly:
+   - German averages 30% longer
+   - Finnish 30-40% longer
+   - French 15-20% longer
+   - Some languages double the length
+   - A button labeled "Submit" (6 characters) becomes "Absenden" in German (8 characters) or "Envoyer la demande" in French (18 characters).
+   - Design every text-containing element with expansion in mind: buttons should size to content rather than fixed widths, navigation items should accommodate 40% growth, and headlines should tolerate 30% expansion without breaking layout.
+   - **IBM globalization expansion table:**
+
+     | Source length (characters) | Expected expansion |
+     | -------------------------- | ------------------ |
+     | 1-10                       | Up to 200%         |
+     | 11-20                      | Up to 80%          |
+     | 21-30                      | Up to 60%          |
+     | 31-50                      | Up to 40%          |
+     | 51-70                      | Up to 31%          |
+     | 70+                        | Up to 30%          |
+
+   Short strings expand the most — disproportionately affecting buttons, labels, tab names, and navigation items.
+
+2. **Build layouts with logical properties, not physical directions.** Replace all directional CSS with logical equivalents:
+   - `margin-left` becomes `margin-inline-start`
+   - `padding-right` becomes `padding-inline-end`
+   - `text-align: left` becomes `text-align: start`
+   - `float: left` becomes `float: inline-start`
+   - This single change makes your layout automatically adapt to RTL scripts without a separate stylesheet. In CSS Grid and Flexbox, use `start` and `end` instead of `left` and `right`.
+   - The `dir="rtl"` attribute on the `<html>` element then flips the entire layout correctly. Test by toggling `dir` in dev tools — if elements jump or overlap, you have physical properties that need migration.
+
+3. **Mirror the entire interface for RTL, not just the text.** RTL is not `text-align: right`. It is a complete interface mirror:
+   - Navigation flows right to left
+   - Progress bars fill right to left
+   - Breadcrumbs read right to left
+   - Back arrows point right (toward the previous page)
+   - Carousels swipe in the opposite direction
+   - Sidebars move to the right side
+   - **Exceptions to mirroring** (do NOT flip these):
+     - Phone numbers and mathematical formulas (always LTR)
+     - Media playback controls (represent temporal direction, not reading direction)
+     - Analog clock faces
+     - Brand logos (remain as designed)
+   - Google's Material Design i18n guidelines document 23 specific mirroring rules — review them before implementing RTL.
+
+4. **Audit every icon and image for cultural sensitivity.** Icons that seem universal often carry culture-specific meanings:
+   - Thumbs-up gesture is offensive in parts of the Middle East, West Africa, and South America
+   - A US-style roadside mailbox icon is unrecognizable outside North America
+   - An owl symbolizes wisdom in Western cultures but is associated with death in some Indian and Middle Eastern cultures
+   - Red means luck/prosperity in China, danger in the West, mourning in South Africa
+   - Audit every icon: (a) does it rely on a culture-specific physical object? (b) does the gesture or symbol have negative connotations in any target market? (c) can it be replaced with a more universal alternative?
+   - Use abstract geometric icons over representational ones when possible.
+
+5. **Never concatenate strings or embed text in images.** String concatenation breaks in every language with different word order:
+   - `"You have " + count + " items in your cart"` fails in Japanese, where the count goes before "items" and both before "cart" with particles between them.
+   - Use ICU MessageFormat or equivalent: `{count, plural, one {You have # item in your cart} other {You have # items in your cart}}`
+   - Pluralization rules vary dramatically: English has 2 forms (singular/plural), French has 3, Arabic has 6, some Slavic languages have 4.
+   - For images: never bake text into images. Use text overlays that can be localized, or provide locale-specific image variants.
+
+6. **Format dates, numbers, and currencies using locale-aware APIs.** Never hardcode formats:
+   - **Dates:** "01/02/2025" is January 2 in the US, February 1 in Europe, ambiguous everywhere. Use `Intl.DateTimeFormat` or equivalent.
+   - **Numbers:** Decimal separator is a period in the US (1,234.56), a comma in Germany (1.234,56), a space-comma in France (1 234,56).
+   - **Currencies:** Always display the currency code — "$" means USD in the US, CAD in Canada, AUD in Australia. Use `Intl.NumberFormat` with `style: 'currency'` and the correct ISO 4217 code.
+   - **Phone numbers:** Vary in length (US: 10 digits, UK: 11, some countries: 7-13) and formatting — use libphonenumber for validation and display.
+
+7. **Design forms that accept international input.** Common assumptions that break internationally:
+   - **Names:** Many cultures use a single name, not first/last. Some use family name first. Some have patronymics. Replace "First Name / Last Name" with "Full Name" or use "Given Name / Family Name" which is culturally neutral.
+   - **Addresses:** Formats vary wildly — Japan puts postal code first and street last, the UK has no state/province, India has PIN codes. Use locale-specific forms or a flexible multi-line input.
+   - **Character limits:** CJK characters carry more meaning per character — a 20-character Japanese string conveys what takes 50+ English characters. Account for this when setting limits.
+
+8. **Implement pseudolocalization as a development practice.** Pseudolocalization transforms English strings into accented variants that test i18n readiness without real translations. Three levels:
+   - **Accented** — replaces ASCII with accented Unicode equivalents (a becomes aa, e becomes ee), simulating expansion and verifying Unicode support.
+   - **Mirrored** — reverses string direction to simulate RTL, exposing hardcoded directional assumptions.
+   - **Elongated** — pads strings with extra characters to reach the expected expansion ratio for the longest target language.
+   - Run pseudolocalization in your staging environment. Any truncated text, broken layouts, or overlapping elements are i18n bugs that would surface only after expensive real translation without this step.
+
+## Details
+
+### Vertical Text and CJK Considerations
+
+Chinese, Japanese, and Korean (CJK) text introduces unique design challenges:
+
+- Characters are set in a square em-box, meaning CJK text at the same font size is visually larger and denser than Latin text
+- Line height for CJK typically needs 1.7-2.0 (versus 1.4-1.6 for Latin) to maintain readability
+- CJK text can be set vertically (`writing-mode: vertical-rl`) in traditional contexts — common in Japanese print, rare in web interfaces
+- Word wrapping does not use spaces — line breaks can occur between any two characters except before certain punctuation
+- CSS `word-break: break-all` is needed for CJK to prevent overflow, but must not be applied to Latin text where it breaks words mid-syllable
+
+### RTL Implementation Checklist
+
+When implementing RTL support, verify each item:
+
+- **CSS logical properties.** All `left`/`right` replaced with `inline-start`/`inline-end`. All `top`/`bottom` replaced with `block-start`/`block-end` where applicable.
+- **Flexbox/Grid direction.** Container direction inherits from `dir` attribute. `flex-direction: row` respects `dir` correctly. But `flex-direction: row-reverse` does not flip and must be audited.
+- **Transforms and animations.** `translateX(100px)` does not automatically mirror. Use `translateX(100%)` with logical properties or JavaScript-based direction detection.
+- **Border radius.** `border-top-left-radius` is physical. Use `border-start-start-radius` (logical) or apply all four radii symmetrically.
+- **Shadows and gradients.** `box-shadow: 5px 0 10px` casts a shadow on the physical right. In RTL, it should appear on the left. Use CSS custom properties that flip based on `dir`.
+- **Scroll direction.** Horizontal scrolling in RTL starts from the right edge. Test carousels, horizontal lists, and overflow containers.
+- **Bidirectional text (BiDi).** When RTL text contains embedded LTR segments (brand names, URLs, code), use the Unicode BiDi algorithm. Wrap LTR segments in `<bdi>` or `<span dir="ltr">` to prevent reordering errors.
+
+### Number and Measurement Localization
+
+Beyond basic number formatting, consider:
+
+- **Measurement units.** The US uses imperial (inches, feet, pounds, Fahrenheit). Nearly every other country uses metric. Localize the unit and convert the value: "5.2 kg" in Germany, "11.5 lbs" in the US.
+- **Week start day.** Calendars start on Sunday in the US, Monday in most of Europe, Saturday in many Middle Eastern countries. A date picker assuming Sunday-start is incorrect for 70% of the world.
+- **Paper sizes.** US uses Letter (8.5x11 in) while the rest of the world uses A4 (210x297mm). A4 is narrower and taller — layouts designed for Letter have different line breaks on A4.
+- **Number grouping.** India groups numbers differently: 1,00,000 (one lakh) instead of 100,000. `Intl.NumberFormat('en-IN')` handles this correctly.
+
+### Anti-Patterns
+
+1. **The "We'll Localize Later" Assumption.** Building an entire product in English with hardcoded strings, fixed-width layouts, and concatenated text, then expecting localization to be a translation pass. By the time localization begins, hundreds of layout assumptions make expansion impossible without a rewrite. The fix: internationalize from day one. Use logical CSS properties, externalize all strings into resource files, and run pseudolocalization in CI from the first sprint.
+
+2. **The Google Translate Test.** Using machine translation to validate i18n readiness. Machine translation produces text that fits in the same space as English (word-for-word translation), missing real expansion. It also masks concatenation issues because it follows English word order. The fix: use pseudolocalization for layout testing and professional translators for final localization. Machine translation is not a substitute for either.
+
+3. **The Flag-for-Language Dropdown.** Using country flags to represent language choices. Flags represent countries, not languages. The Spanish flag does not represent 400 million Latin American Spanish speakers. Some countries have multiple official languages (Switzerland has 4, India has 22). The fix: use language names written in their own script — "Deutsch" not "German," "Espanol" not "Spanish" — in a text-based selector.
+
+4. **The Right-to-Left Afterthought.** Adding RTL support by applying `direction: rtl` and `text-align: right` and calling it done. This misses icon mirroring, shadow direction, animation direction, progress bars, form alignment, navigation hierarchy, and dozens of other spatial elements. The fix: implement RTL using logical properties from the start, test with real Arabic/Hebrew content, and use a native RTL speaker for QA.
+
+5. **Hardcoded Pluralization.** Using `count === 1 ? "item" : "items"`. This breaks in Arabic (6 plural forms), Polish (3 forms with complex rules), and even French (zero is singular). The fix: use ICU MessageFormat or `Intl.PluralRules`, which implements CLDR plural rules for all locales.
+
+### Real-World Examples
+
+**Airbnb's i18n Design System.** Airbnb operates in 220+ countries and 62 languages. Their design system enforces i18n at the component level:
+
+- Every text-containing component has a `maxLines` prop with ellipsis behavior
+- Every layout uses CSS logical properties
+- Every icon was audited for cultural sensitivity (they replaced a house icon resembling a Western detached home with a more universal "shelter" glyph)
+- Pseudolocalization runs on every PR — any string that truncates or overflows at 150% expansion blocks merge
+- Launching a new language requires zero layout changes to existing components.
+
+**Slack's RTL Support.** When Slack added Arabic and Hebrew, they discovered mirroring broke threaded messages: the reply indicator line used hardcoded `border-left` and `margin-left`. In RTL, the line appeared on the wrong side, disconnecting replies from parents. They migrated 2,400+ CSS declarations from physical to logical properties over 6 months. The hardest part was custom canvas-rendered elements (emoji picker positioning, rich text cursor behavior) where CSS logical properties do not apply and direction-aware JavaScript was needed.
+
+**Mozilla's Pontoon Localization Platform.** Mozilla localizes Firefox into 90+ languages. Pontoon enforces i18n best practices at the string level:
+
+- Rejects strings containing concatenation (flags them with "this string appears to be concatenated — use a single localizable string with placeholders")
+- Warns when a string exceeds 40 characters without a line-break allowance
+- Provides real-time preview showing how the translated string renders in the actual UI
+- Localizers can see that their German translation will overflow a toolbar button before submitting it.
+
+**WhatsApp's Bidirectional Text Handling.** WhatsApp supports mixed-direction text in messages (Arabic user sending a message with an English URL). They use the Unicode Bidirectional Algorithm with explicit directional marks: when the app detects a message starting with an RTL character, it wraps the message in a Right-to-Left Mark (U+200F). Embedded LTR segments (URLs, numbers, brand names) are isolated using First Strong Isolate (U+2068). Without these marks, a message containing "Visit www.example.com" in Arabic reorders URL segments, breaking the link.
+
+## Source
+
+- W3C — "Internationalization Best Practices for Spec Developers" (2023)
+- Google Material Design — "Bidirectionality" guidelines (2024), RTL mirroring rules
+- IBM Globalization Guidelines — text expansion ratios and design considerations
+- CLDR (Unicode Common Locale Data Repository) — plural rules, date/number formats by locale
+- Apple Human Interface Guidelines — "Internationalization and Localization" (2024)
+- Esselink, B. — _A Practical Guide to Localization_ (2000), foundational localization methodology
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## 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.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/codex/design-i18n-design/skill.yaml

@@ -0,0 +1,35 @@
+name: design-i18n-design
+version: "1.0.0"
+description: Designing for internationalization — text expansion, RTL layout, icon cultural sensitivity, date/number/currency formatting, pseudolocalization
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - design-responsive-strategy
+  - design-typography-fundamentals
+  - design-content-density
+stack_signals: []
+keywords:
+  - internationalization
+  - i18n
+  - RTL
+  - bi-directional
+  - text-expansion
+  - pseudolocalization
+  - localization
+  - cultural-sensitivity
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/design-iconography/SKILL.md

@@ -0,0 +1,169 @@
+# Iconography
+
+> Icon design principles — optical sizing, stroke consistency, pixel grid alignment, metaphor clarity, icon families, filled vs outlined states, and icon as a systematic visual language
+
+## When to Use
+
+- Building or selecting an icon set for a product or design system
+- Evaluating whether icons are optically consistent across sizes and weights
+- Choosing between filled, outlined, or two-tone icon variants for different contexts
+- Aligning icons to a pixel grid to prevent subpixel rendering blur
+- Designing custom icons that need to feel native to an existing icon family
+- Selecting icon metaphors that communicate function without ambiguity
+- Implementing icon size scales that maintain legibility from 12px to 48px
+- Auditing an icon set for visual weight consistency across different shapes
+
+## Instructions
+
+1. **Design to the pixel grid, not the mathematical center.** Every icon canvas has a pixel grid — typically 16x16, 20x20, or 24x24. Align all straight edges to full pixel boundaries. Diagonal and curved lines are exempt from grid snapping but should start and end on pixel intersections. Decision procedure: at your target render size, export the icon at 1x and zoom to 800%. If any horizontal or vertical edge falls between pixels, the renderer will anti-alias it — producing a blurry 2px line where you intended a crisp 1px line. Apple's SF Symbols enforce a 1px grid at each of 3 scales (small, medium, large) to guarantee sharpness on retina and non-retina displays alike.
+
+2. **Establish a stroke weight system and never deviate.** Stroke weight is the single most visible consistency signal in an icon family. Material Symbols uses a stroke weight axis from 100 to 700 in 100-unit increments. For a typical product icon set at 24px canvas, common stroke weights are:
+   - **1.5px** — light, editorial, minimal (Vercel, Linear)
+   - **2px** — standard, balanced (Feather Icons, Lucide)
+   - **2.5px** — medium, slightly bold (Heroicons outline)
+   - **3px** — bold, high-contrast, touch-friendly (Material Symbols at weight 400)
+
+   Decision procedure: pick ONE stroke weight for your entire icon set. If you need weight variation, define explicit weight tiers (light/regular/bold) with specific pixel values. Never approximate — a 1.75px stroke next to a 2px stroke is visibly inconsistent.
+
+3. **Apply optical sizing, not linear scaling.** A 16px icon is not a scaled-down 24px icon. At smaller sizes, details collapse: 1px gaps disappear, thin strokes become invisible, interior detail becomes noise. Optical sizing means redesigning the icon for each size tier. Apple's SF Symbols provide 3 optical scales:
+   - **Small (≤20pt):** Increased stroke weight, simplified interior detail, larger counters
+   - **Medium (20-26pt):** Standard proportions
+   - **Large (≥26pt):** Finer detail, thinner relative stroke weight, decorative elements preserved
+
+   GitHub's Octicons ship two discrete sizes — 16px and 24px — with different path geometry for each. The 16px `repo` icon has 2 simplified elements; the 24px version has 4 detailed elements. Concrete rule: if your icon set supports sizes below 20px, you need a separate optical variant with at minimum 0.5px thicker strokes and 30-50% fewer interior details.
+
+4. **Choose icon metaphors that survive the 5-second test.** Show the icon to someone unfamiliar with your product for 5 seconds. If they cannot identify the referent or action, the metaphor is too abstract. Proven metaphors:
+   - **Gear** = settings (near-universal, used by iOS, Android, Windows, web)
+   - **Magnifying glass** = search (universal)
+   - **House** = home (universal)
+   - **Pencil** = edit (universal, but "pen" variant can read as "draw")
+   - **Trash can** = delete (universal in Western UI; less clear in some Asian markets)
+   - **Hamburger (three lines)** = menu (learned convention, not intuitive — fails with older or non-tech-savvy users)
+   - **Floppy disk** = save (skeuomorphic holdover — still recognized but increasingly opaque to younger users)
+
+   When no established metaphor exists, prefer a concrete noun over an abstract concept. "Cloud with arrow" for upload is more scannable than an abstract upward-pointing triangle.
+
+5. **Define the filled vs. outlined decision systematically.** Do not mix arbitrarily. The two styles carry different visual weight and semantic implications:
+   - **Outlined icons** — lighter visual weight, recede in the interface, better for navigation bars, toolbars, and inactive states. They read well at medium-to-large sizes (20px+). At small sizes (below 16px), outlines can become indistinct.
+   - **Filled icons** — heavier visual weight, advance in the visual hierarchy, better for active/selected states, CTAs, and small sizes where outline detail would collapse. They carry more brand personality.
+
+   Google's Material Symbols uses filled for selected/active states and outlined for unselected/inactive states — a toggle pattern. iOS Tab Bar follows the same convention: outlined icons for unselected tabs, filled for the active tab. Decision procedure: use outlined as the default state. Switch to filled for selected, active, or emphasized states. Never use filled and outlined versions of the same icon at the same hierarchy level — the weight difference creates unintended emphasis.
+
+6. **Maintain consistent optical weight across shape families.** A circle, a square, and a triangle at the same bounding box size do not appear the same size. Circles and triangles look smaller than squares of identical dimensions — this is a well-documented optical illusion. Compensate:
+   - **Circles** should extend ~2% beyond the square icon's safe zone
+   - **Triangles** should extend ~4-6% beyond the safe zone vertically (apex extends past the grid)
+   - **Tall, narrow shapes** should extend ~2% horizontally past the safe zone
+
+   Material Design's icon grid includes a "trim area" (the full canvas) and a "live area" (where content sits, slightly inset). The live area is 20x20 inside a 24x24 canvas. But circular icons like the `info` circle occupy 22x22 — exceeding the live area — to optically match the weight of square icons that sit within 20x20.
+
+7. **Build icon families, not icon collections.** A family shares DNA: consistent stroke weight, consistent corner radius, consistent level of detail, consistent metaphor style (outline realism vs. geometric abstraction). When adding a new icon to an existing family, match these attributes before matching the concept. A geometrically perfect new icon that has 1px rounded corners in a set using 2px rounded corners will feel foreign regardless of how well-drawn it is. Airbnb's icon system enforces: 2px stroke, 2px corner radius, 24px canvas, no fills, single-color rendering — every icon must pass all five constraints to enter the family.
+
+## Details
+
+### Keyline Shapes and Alignment Grids
+
+Professional icon sets define keyline shapes — canonical bounding geometries that icons are designed around. Material Design defines four keylines for its 24px grid:
+
+| Keyline Shape        | Dimensions | Use Case                                  |
+| -------------------- | ---------- | ----------------------------------------- |
+| Square               | 18x18      | Rectangular content (document, screen)    |
+| Circle               | 20x20      | Circular content (avatar, globe, record)  |
+| Vertical rectangle   | 16x20      | Portrait content (person, bottle, phone)  |
+| Horizontal rectangle | 20x16      | Landscape content (laptop, car, envelope) |
+
+All four keylines produce optically equivalent weight within the 24px canvas. When designing a new icon, first determine which keyline shape it falls into, then draw within that keyline. This prevents the common failure of icons that are technically the same canvas size but visually different weights.
+
+### Icon as Interaction Affordance
+
+Icons in interactive contexts need touch/click targets that exceed their visual bounds. WCAG 2.5.8 requires a minimum 24x24 CSS pixel target size. Apple's HIG recommends 44x44pt minimum. This means:
+
+- A 16px visual icon needs at minimum 24px of tappable area (4px padding per side)
+- A 24px visual icon should have 44px tappable area on mobile (10px padding per side)
+- Interactive icon buttons should declare `min-width` and `min-height` on the button element, not on the icon SVG — the icon stays visually small while the hit target stays accessible
+
+### Stroke Caps and Joins
+
+Seemingly minor stroke attributes create visible inconsistency at scale:
+
+- **Round caps** — strokes end with a semicircle. Adds ~1px visual length to each stroke terminus. Feels softer. Used by Feather Icons, Lucide, and most modern sets.
+- **Square/butt caps** — strokes end flat. Feels more precise and technical. Used in some engineering and drafting-style icon sets.
+- **Round joins** — corners are radiused. Feels friendly and organic. Matches round caps.
+- **Miter joins** — corners are sharp. Feels precise and geometric. Can produce spiky artifacts at acute angles.
+
+Decision procedure: round caps + round joins for consumer products (friendly, approachable). Square caps + miter joins for technical/professional products. Never mix cap styles within an icon family.
+
+### Anti-Patterns
+
+1. **Stroke Weight Drift.** Mixing 1.5px, 2px, and 2.25px strokes within the same icon set because individual designers "eyeballed" the weight. At UI scale, even 0.25px differences are visible and make the set feel unpolished. Fix: define an exact stroke weight in the design system tokens, enforce it in the SVG export pipeline, and lint exported SVGs for stroke-width consistency. Lucide runs automated CI checks that reject contributions with non-conforming stroke weights.
+
+2. **Detail Overload at Small Sizes.** Designing an icon at 48px with fine interior detail (hatching, small counters, thin negative space) and rendering it at 16px where the detail becomes muddy noise. Fix: follow Apple's optical sizing model — create separate path geometry for each size tier. At minimum, remove interior detail and increase stroke weight for any icon rendered below 20px.
+
+3. **Metaphor Ambiguity.** Using a "star" icon for both "favorites" and "ratings" in the same product. Or using a "bell" for both "notifications" and "alarms." When the same visual metaphor maps to two different functions, users cannot build reliable mental models. Fix: one metaphor, one function per product. If you need both favorites and ratings, use a star for one and a heart or bookmark for the other. Document the metaphor map in your design system.
+
+4. **Pixel Grid Misalignment.** Designing icons in Figma at 1x without checking the pixel grid, resulting in paths that fall on half-pixel boundaries. The icon looks crisp in Figma's vector preview but renders blurry in the browser at 1x resolution. Fix: in Figma, enable "Snap to pixel grid" and verify at 1x export. In SVG code, audit path coordinates — values like `x="3.5"` on horizontal edges indicate half-pixel alignment. Round to integers for horizontal/vertical edges.
+
+5. **Filled/Outlined Inconsistency.** Using filled icons for some navigation items and outlined for others at the same hierarchy level, creating unintended visual weight differences that imply hierarchy where none exists. Fix: apply the Material Symbols convention — all icons at the same level use the same variant. Reserve the alternate variant for state changes (active/inactive).
+
+### Real-World Examples
+
+**Apple SF Symbols — The Gold Standard for Optical Sizing.** SF Symbols offers over 5,000 icons with 9 weights (ultralight through black) and 3 scales (small, medium, large), producing 27 variants per symbol. Each variant has unique path geometry — the small-scale, ultralight `gear` has thicker relative strokes and fewer teeth than the large-scale, bold `gear`. The system also supports variable color (progressive fill based on a 0-1 value) and automatic alignment with San Francisco text at any size. SF Symbols enforces a 1px stroke grid at each scale, ensuring pixel-perfect rendering on all Apple displays. Key lesson: optical sizing is not optional — it is the difference between a professional and an amateur icon system.
+
+**GitHub Octicons — Two-Size Discrete System.** Octicons ships exactly two sizes: 16px and 24px. Each size has independent path geometry. The 16px `alert` triangle has 2px strokes and minimal interior detail (just the exclamation mark). The 24px `alert` has 1.5px relative strokes and additional interior structure. GitHub chose discrete sizes over continuous scaling because their UI uses only these two sizes — a pragmatic constraint that eliminates optical sizing edge cases. Key lesson: you do not need a continuous size spectrum. Identify your actual render sizes and optimize for those.
+
+**Material Symbols — Weight and Fill as Axes.** Material Symbols treats stroke weight (100-700), fill (0 or 1), and optical size (20, 24, 40, 48) as independent variable font axes. A single icon file can render at any combination. At weight 400, optical size 24, fill 0: the icon shows 2px outlined strokes. At weight 700, optical size 48, fill 1: the same icon renders as a bold filled shape. This approach eliminates the need for separate icon files per variant — the browser interpolates the correct paths via variable font technology. Key lesson: if your icon system must support many contexts (navigation, content, headers, mobile, desktop), variable axes dramatically reduce maintenance cost.
+
+**Vercel — Minimalist Monochrome.** Vercel's icon set uses 1.5px strokes, no fills, single color (foreground only), and a deliberately constrained vocabulary (~60 icons). Every icon is reducible to 2-3 strokes — the `deploy` icon is a single upward arrow with a horizontal base line. This extreme minimalism aligns with Vercel's brand: developer-focused, no-nonsense, maximally functional. Key lesson: icon family personality comes from constraints. Fewer strokes, fewer icons, tighter rules = stronger visual identity.
+
+**Airbnb Icons — Hospitality Through Roundness.** Airbnb's icon system uses 2px strokes with 2px corner radius — every corner is rounded, every terminal is rounded. This produces icons that feel warm and approachable, matching the "belong anywhere" brand. The roundness is a deliberate departure from the sharp geometric style of tech-company icon sets. Even functional icons like "filter" and "map pin" carry the rounded DNA. Key lesson: corner radius is a brand signal. Sharp corners = precision, authority. Rounded corners = warmth, approachability. The choice must be consistent and intentional.
+
+### Icon Accessibility
+
+Icons carry interaction and meaning, making accessibility non-negotiable:
+
+- **Always pair icons with text labels in navigation.** Unlabeled icon-only navigation (a common pattern in mobile tab bars and sidebar menus) fails for users who cannot map abstract symbols to functions. Nielsen Norman Group research shows that icon + text labels increase discoverability by 88% compared to icon-only interfaces. If space constraints force icon-only display, provide a tooltip on hover/long-press that matches the text label exactly.
+- **Use `aria-label` or `aria-labelledby` on interactive icon buttons.** A button containing only an SVG icon has no accessible name unless explicitly provided. `<button aria-label="Close dialog"><svg>...</svg></button>` is the minimum. Never rely on the icon's visual metaphor for screen reader users.
+- **Decorative icons get `aria-hidden="true"`.** An icon next to a text label that repeats the icon's meaning (a trash can icon next to "Delete") should be hidden from screen readers to avoid redundancy: `<svg aria-hidden="true">`.
+- **Ensure 3:1 contrast ratio for non-text UI.** WCAG 2.2 Success Criterion 1.4.11 requires icons used as interactive affordances to meet 3:1 contrast against their background. A light gray icon (`#9CA3AF`, ~4.5 relative luminance) on a white background (`#FFFFFF`, 21 relative luminance) has a contrast ratio of 2.8:1 — failing the requirement. Use `#6B7280` (4.6:1) or darker.
+
+### SVG Optimization and Delivery
+
+Icon delivery affects both rendering quality and performance:
+
+- **Use inline SVG for interactive icons** that need CSS styling (hover color changes, transitions). Inline SVG allows `currentColor` inheritance and CSS custom property theming. An icon that changes color on hover needs to be inline, not an `<img>` reference.
+- **Use SVG sprite sheets for large icon sets.** A product using 60+ icons should bundle them into a single `<svg>` sprite with `<symbol>` elements, referenced via `<use href="#icon-name">`. This reduces HTTP requests to 1 and enables browser caching of the entire set.
+- **Optimize path data.** Run all production SVGs through SVGO with `removeViewBox: false` (viewBox is needed for responsive scaling) and `removeDimensions: true` (use CSS for sizing). A typical icon SVG optimizes from 800 bytes to 200 bytes — a 75% reduction.
+- **Standardize viewBox.** Every icon in a family must use the same `viewBox` — typically `"0 0 24 24"` for a 24px grid. Inconsistent viewBoxes cause icons to render at different effective sizes even when the CSS `width` and `height` are identical.
+
+### Icon Naming Conventions
+
+A systematic naming convention prevents icon confusion at scale:
+
+- **Format:** `{category}-{object}-{variant}`. Example: `nav-home-filled`, `action-delete-outlined`, `status-check-circle`.
+- **Categories:** `nav` (navigation), `action` (user actions), `status` (state indicators), `content` (content type indicators), `social` (social platform logos).
+- **Variants:** `filled`, `outlined`, `two-tone`, `sharp`. Never use ambiguous suffixes like `v2` or `alt`.
+- **Avoid synonym collision:** If the set has both `close` (X mark) and `cancel` (circle X), the names must clearly distinguish them: `action-close` vs. `action-cancel-circle`.
+
+## Source
+
+- Apple Human Interface Guidelines — SF Symbols (2024)
+- Material Design 3 — Icon Design Principles (2024)
+- GitHub Octicons — Design Guidelines
+- Feather Icons — Design Principles
+- Airbnb Design — Iconography Standards
+- WCAG 2.2 — Non-text Contrast (1.4.11), Name, Role, Value (4.1.2)
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## 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.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.