@bastani/atomic 0.8.20-0 → 0.8.21-0

package/dist/builtin/workflows/skills/impeccable/reference/typography.md

@@ -1,159 +0,0 @@
-# Typography
-
-## Classic Typography Principles
-
-### Vertical Rhythm
-
-Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony; text and space share a mathematical foundation.
-
-### Modular Scale & Hierarchy
-
-The common mistake: too many font sizes that are too close together (14px, 15px, 16px, 18px...). This creates muddy hierarchy.
-
-**Use fewer sizes with more contrast.** A 5-size system covers most needs:
-
-| Role | Typical Ratio | Use Case |
-|------|---------------|----------|
-| xs | 0.75rem | Captions, legal |
-| sm | 0.875rem | Secondary UI, metadata |
-| base | 1rem | Body text |
-| lg | 1.25-1.5rem | Subheadings, lead text |
-| xl+ | 2-4rem | Headlines, hero text |
-
-Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.
-
-### Readability & Measure
-
-Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length: narrow columns need tighter leading, wide columns need more.
-
-**Non-obvious**: Light text on dark backgrounds needs compensation on three axes, not just one. Bump line-height by 0.05–0.1, add a touch of letter-spacing (0.01–0.02em), and optionally step the body weight up one notch (regular → medium). The perceived weight drops across all three; fix all three.
-
-**Paragraph rhythm**: Pick either space between paragraphs OR first-line indentation. Never both. Digital usually wants space; editorial/long-form can justify indent-only.
-
-## Font Selection & Pairing
-
-The tactical selection procedure and the reflex-reject list live in [reference/brand.md](brand.md) under **Font selection procedure** and **Reflex-reject list** (loaded for brand-register tasks). The rest of this section covers the adjacent knowledge: anti-reflex corrections, system font use, and pairing rules.
-
-### Anti-reflexes worth defending against
-
-- A technical/utilitarian brief does NOT need a serif "for warmth." Most tech tools should look like tech tools.
-- An editorial/premium brief does NOT need the same expressive serif everyone is using right now. Premium can be Swiss-modern, can be neo-grotesque, can be a literal monospace, can be a quiet humanist sans.
-- A children's product does NOT need a rounded display font. Kids' books use real type.
-- A "modern" brief does NOT need a geometric sans. The most modern thing you can do is not use the font everyone else is using.
-
-**System fonts are underrated**: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` looks native, loads instantly, and is highly readable. Consider this for apps where performance > personality.
-
-### Pairing Principles
-
-**The non-obvious truth**: You often don't need a second font. One well-chosen font family in multiple weights creates cleaner hierarchy than two competing typefaces. Only add a second font when you need genuine contrast (e.g., display headlines + body serif).
-
-When pairing, contrast on multiple axes:
-- Serif + Sans (structure contrast)
-- Geometric + Humanist (personality contrast)
-- Condensed display + Wide body (proportion contrast)
-
-**Never pair fonts that are similar but not identical** (e.g., two geometric sans-serifs). They create visual tension without clear hierarchy.
-
-### Web Font Loading
-
-The layout shift problem: fonts load late, text reflows, and users see content jump. Here's the fix:
-
-```css
-/* 1. Use font-display: swap for visibility */
-@font-face {
-  font-family: 'CustomFont';
-  src: url('font.woff2') format('woff2');
-  font-display: swap;
-}
-
-/* 2. Match fallback metrics to minimize shift */
-@font-face {
-  font-family: 'CustomFont-Fallback';
-  src: local('Arial');
-  size-adjust: 105%;        /* Scale to match x-height */
-  ascent-override: 90%;     /* Match ascender height */
-  descent-override: 20%;    /* Match descender depth */
-  line-gap-override: 10%;   /* Match line spacing */
-}
-
-body {
-  font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
-}
-```
-
-Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these overrides automatically.
-
-**`swap` vs `optional`**: `swap` shows fallback text immediately and FOUT-swaps when the web font arrives. `optional` uses the fallback if the web font misses a small load budget (~100ms) and avoids the shift entirely. Pick `optional` when zero layout shift matters more than seeing the branded font on slow networks.
-
-**Preload the critical weight only**: typically the regular-weight body font used above the fold. Preloading every weight costs more bandwidth than it saves.
-
-**Variable fonts for 3+ weights or styles**: a single variable font file is usually smaller than three static weight files, gives fractional weight control, and pairs well with `font-optical-sizing: auto`. For 1–2 weights, static is fine.
-
-## Modern Web Typography
-
-### Fluid Type
-
-Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the viewport. The middle value (e.g., `5vw + 1rem`) controls scaling rate (higher vw = faster scaling). Add a rem offset so it doesn't collapse to 0 on small screens.
-
-**Use fluid type for**: Headings and display text on marketing/content pages where text dominates the layout and needs to breathe across viewport sizes.
-
-**Use fixed `rem` scales for**: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI; fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.
-
-**Bound your clamp()**: keep `max-size ≤ ~2.5 × min-size`. Wider ratios break the browser's zoom and reflow behaviour and make large viewports feel like the page is shouting.
-
-**Scale container width and font-size together** so effective character measure stays in the 45–75ch band at every viewport. A heading that widens faster than its container drifts out of the comfortable measure at the top end.
-
-### OpenType Features
-
-Most developers don't know these exist. Use them for polish:
-
-```css
-/* Tabular numbers for data alignment */
-.data-table { font-variant-numeric: tabular-nums; }
-
-/* Proper fractions */
-.recipe-amount { font-variant-numeric: diagonal-fractions; }
-
-/* Small caps for abbreviations */
-abbr { font-variant-caps: all-small-caps; }
-
-/* Disable ligatures in code */
-code { font-variant-ligatures: none; }
-
-/* Enable kerning (usually on by default, but be explicit) */
-body { font-kerning: normal; }
-```
-
-Check what features your font supports at [Wakamai Fondue](https://wakamaifondue.com/).
-
-### Rendering polish
-
-```css
-/* Even out heading line lengths (browser picks better break points) */
-h1, h2, h3 { text-wrap: balance; }
-
-/* Reduce orphans and ragged endings in long prose */
-article p { text-wrap: pretty; }
-
-/* Variable fonts: pick the right optical-size master automatically */
-body { font-optical-sizing: auto; }
-```
-
-**ALL-CAPS tracking**: capitals sit too close at default spacing. Add 5–12% letter-spacing (`letter-spacing: 0.05em` to `0.12em`) to short all-caps labels, eyebrows, and small headings. Real small caps (via `font-variant-caps`) need the same treatment, slightly gentler.
-
-## Typography System Architecture
-
-Name tokens semantically (`--text-body`, `--text-heading`), not by value (`--font-size-16`). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.
-
-## Accessibility Considerations
-
-Beyond contrast ratios (which are well-documented), consider:
-
-- **Never disable zoom**: `user-scalable=no` breaks accessibility. If your layout breaks at 200% zoom, fix the layout.
-- **Use rem/em for font sizes**: This respects user browser settings. Never `px` for body text.
-- **Minimum 16px body text**: Smaller than this strains eyes and fails WCAG on mobile.
-- **Adequate touch targets**: Text links need padding or line-height that creates 44px+ tap targets.
-
----
-
-**Avoid**: More than 2-3 font families per project. Skipping fallback font definitions. Ignoring font loading performance (FOUT/FOIT). Using decorative fonts for body text.

package/dist/builtin/workflows/skills/impeccable/reference/ux-writing.md

@@ -1,107 +0,0 @@
-# UX Writing
-
-## The Button Label Problem
-
-**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
-
-| Bad | Good | Why |
-|-----|------|-----|
-| OK | Save changes | Says what will happen |
-| Submit | Create account | Outcome-focused |
-| Yes | Delete message | Confirms the action |
-| Cancel | Keep editing | Clarifies what "cancel" means |
-| Click here | Download PDF | Describes the destination |
-
-**For destructive actions**, name the destruction:
-- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
-- "Delete 5 items" not "Delete selected" (show the count)
-
-## Error Messages: The Formula
-
-Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
-
-### Error Message Templates
-
-| Situation | Template |
-|-----------|----------|
-| **Format error** | "[Field] needs to be [format]. Example: [example]" |
-| **Missing required** | "Please enter [what's missing]" |
-| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
-| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
-| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
-
-### Don't Blame the User
-
-Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
-
-## Empty States Are Opportunities
-
-Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
-
-## Voice vs Tone
-
-**Voice** is your brand's personality, consistent everywhere.
-**Tone** adapts to the moment.
-
-| Moment | Tone Shift |
-|--------|------------|
-| Success | Celebratory, brief: "Done! Your changes are live." |
-| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
-| Loading | Reassuring: "Saving your work..." |
-| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
-
-**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
-
-## Writing for Accessibility
-
-**Link text** must have standalone meaning: "View pricing plans" not "Click here". **Alt text** describes information, not the image: "Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
-
-## Writing for Translation
-
-### Plan for Expansion
-
-German text is ~30% longer than English. Allocate space:
-
-| Language | Expansion |
-|----------|-----------|
-| German | +30% |
-| French | +20% |
-| Finnish | +30-40% |
-| Chinese | -30% (fewer chars, but same width) |
-
-### Translation-Friendly Patterns
-
-Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
-
-## Consistency: The Terminology Problem
-
-Pick one term and stick with it:
-
-| Inconsistent | Consistent |
-|--------------|------------|
-| Delete / Remove / Trash | Delete |
-| Settings / Preferences / Options | Settings |
-| Sign in / Log in / Enter | Sign in |
-| Create / Add / New | Create |
-
-Build a terminology glossary and enforce it. Variety creates confusion.
-
-## Avoid Redundant Copy
-
-If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
-
-## Loading States
-
-Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
-
-## Confirmation Dialogs: Use Sparingly
-
-Most confirmation dialogs are design failures; consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
-
-## Form Instructions
-
-Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
-
----
-
-**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.

package/dist/builtin/workflows/skills/impeccable/scripts/load-context.mjs

@@ -1,141 +0,0 @@
-/**
- * Shared context loader for every impeccable command that needs to know
- * "who is this for" and "what does this look like".
- *
- * Input: project root (process.cwd()).
- *
- * Output (JSON to stdout):
- *   {
- *     hasProduct: boolean,        // PRODUCT.md found (or auto-migrated)
- *     product: string | null,     // PRODUCT.md contents
- *     productPath: string | null, // relative path
- *     hasDesign: boolean,         // DESIGN.md found
- *     design: string | null,      // DESIGN.md contents
- *     designPath: string | null,
- *     migrated: boolean,          // true if we auto-renamed .impeccable.md -> PRODUCT.md
- *     contextDir: string,         // absolute path of the directory the files were found in
- *   }
- *
- * Filename matching is case-insensitive for PRODUCT.md and DESIGN.md. The
- * Google DESIGN.md convention is uppercase at repo root; Kiro-style and
- * lowercase variants are also matched so users don't get punished for case.
- *
- * Lookup directory resolution (first match wins):
- *   1. process.env.IMPECCABLE_CONTEXT_DIR (absolute or relative to cwd)
- *   2. cwd, if PRODUCT.md / DESIGN.md / .impeccable.md is there (back-compat)
- *   3. Auto-fallback subdirectories of cwd: .agents/context/, then docs/
- *   4. cwd as a default "no context found" location
- *
- * Legacy `.impeccable.md` -> PRODUCT.md migration only fires at cwd root;
- * fallback directories are read-only as far as auto-rename is concerned.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
-const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
-const LEGACY_NAMES = ['.impeccable.md'];
-const FALLBACK_DIRS = ['.agents/context', 'docs'];
-
-/**
- * Resolve the directory that holds PRODUCT.md / DESIGN.md for
- * this project. Exported so other scripts (e.g. live-server.mjs) can read the
- * design files from the same location the loader uses.
- */
-export function resolveContextDir(cwd = process.cwd()) {
-  // 1. Explicit override
-  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
-  if (envDir && envDir.trim()) {
-    const trimmed = envDir.trim();
-    return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
-  }
-
-  // 2. cwd wins if any canonical or legacy file is there. We check legacy too
-  //    so the auto-migration path in loadContext stays predictable.
-  if (firstExisting(cwd, [...PRODUCT_NAMES, ...DESIGN_NAMES, ...LEGACY_NAMES])) {
-    return cwd;
-  }
-
-  // 3. Auto-fallback subdirs. Match if PRODUCT.md or DESIGN.md is present;
-  //    legacy `.impeccable.md` does not pull the lookup into a fallback dir.
-  for (const rel of FALLBACK_DIRS) {
-    const candidate = path.resolve(cwd, rel);
-    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
-      return candidate;
-    }
-  }
-
-  // 4. Nothing found — keep the historical "default to cwd" behaviour so the
-  //    caller's `hasProduct === false` branch still fires the same way.
-  return cwd;
-}
-
-export function loadContext(cwd = process.cwd()) {
-  let migrated = false;
-  const contextDir = resolveContextDir(cwd);
-
-  // 1. Look for PRODUCT.md (case-insensitive) in the resolved dir
-  let productPath = firstExisting(contextDir, PRODUCT_NAMES);
-
-  // 2. Legacy: if no PRODUCT.md but .impeccable.md exists at cwd root, rename
-  //    it in place. We only migrate at the root — fallback dirs are read-only
-  //    so we don't surprise users by mutating files under docs/ or .agents/.
-  if (!productPath && contextDir === cwd) {
-    const legacyPath = firstExisting(cwd, LEGACY_NAMES);
-    if (legacyPath) {
-      const newPath = path.join(cwd, 'PRODUCT.md');
-      try {
-        fs.renameSync(legacyPath, newPath);
-        productPath = newPath;
-        migrated = true;
-      } catch {
-        // Rename failed (permissions, etc.) — fall back to reading legacy in place
-        productPath = legacyPath;
-      }
-    }
-  }
-
-  // 3. DESIGN.md (case-insensitive)
-  const designPath = firstExisting(contextDir, DESIGN_NAMES);
-
-  const product = productPath ? safeRead(productPath) : null;
-  const design = designPath ? safeRead(designPath) : null;
-
-  return {
-    hasProduct: !!product,
-    product,
-    productPath: productPath ? path.relative(cwd, productPath) : null,
-    hasDesign: !!design,
-    design,
-    designPath: designPath ? path.relative(cwd, designPath) : null,
-    migrated,
-    contextDir,
-  };
-}
-
-function firstExisting(dir, names) {
-  for (const name of names) {
-    const abs = path.join(dir, name);
-    if (fs.existsSync(abs)) return abs;
-  }
-  return null;
-}
-
-function safeRead(p) {
-  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
-}
-
-// ---------------------------------------------------------------------------
-// CLI mode — print the context as JSON
-// ---------------------------------------------------------------------------
-
-function cli() {
-  const result = loadContext(process.cwd());
-  console.log(JSON.stringify(result, null, 2));
-}
-
-const _running = process.argv[1];
-if (_running?.endsWith('load-context.mjs') || _running?.endsWith('load-context.mjs/')) {
-  cli();
-}