godpowers 0.15.0

package/references/design/MOTION.md

@@ -0,0 +1,120 @@
+# Motion
+
+> Godpowers' baseline guidance for animation and transition.
+> Shallower than
+> [Impeccable's motion-design reference](https://github.com/pbakaus/impeccable/blob/main/skill/reference/motion-design.md).
+
+## Three durations, three easings
+
+Most products need only this:
+
+| Duration | Use |
+|---|---|
+| `100ms` | Hover states, focus rings, color shifts |
+| `200ms` | Element appear/disappear, expand/collapse |
+| `400ms` | Page transitions, route changes, modals |
+
+```css
+:root {
+  --motion-fast: 100ms;
+  --motion-default: 200ms;
+  --motion-slow: 400ms;
+}
+```
+
+Anything longer than 500ms feels broken or theatrical (unless it's a
+page transition with intentional staging).
+
+## Easings
+
+| Curve | When |
+|---|---|
+| `ease-out` (cubic-bezier(0.16, 1, 0.3, 1)) | Default for most things |
+| `ease-in-out` (cubic-bezier(0.65, 0, 0.35, 1)) | Both ends matter (modals, drawers) |
+| `linear` | Loading bars, scroll progress, durations the user controls |
+
+Avoid:
+
+- **Bounce** (cubic-bezier with overshoot): feels dated, mid-2010s
+- **Elastic** / spring with too much stiffness: distracting in product UI
+- **ease-in alone**: feels heavy, fights user attention
+
+## Anti-patterns
+
+- **Animating everything.** Page-level animations on every interaction
+  are exhausting. Restrict to: state changes, navigation, gating.
+- **Slow exits.** When something should leave the screen (modal close,
+  toast dismiss), use `100ms`. Slow exits make the user wait.
+- **Motion without intent.** A spinning logo, ambient particles,
+  hover pulses on every card. Decoration that doesn't serve.
+- **Ignoring `prefers-reduced-motion`.** Always honor.
+- **Bounce on production UI.** Acceptable in marketing/illustration;
+  in product UI it reads as toy.
+
+## prefers-reduced-motion
+
+Always respect:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+Or in JS via `window.matchMedia('(prefers-reduced-motion: reduce)')`.
+Disable nonessential motion entirely; keep essential transitions
+near-instant.
+
+## Staggering
+
+When multiple elements animate together (e.g., a list rendering),
+stagger by 30-50ms per item, max 8-10 items before the cascade feels
+like a wait.
+
+```js
+items.forEach((item, i) => {
+  item.style.transitionDelay = `${i * 40}ms`;
+});
+```
+
+Beyond 10 items: animate the container, not each child.
+
+## Scroll-driven motion
+
+Use sparingly. One scroll-tied animation per long page is plenty.
+
+Acceptable:
+- Hero parallax (subtle, < 30% velocity ratio)
+- Progress indicator at the top
+- Reveal-on-scroll for hero sections
+
+Not acceptable:
+- Every section parallax
+- Counter-scroll text
+- Multiple scroll-pinned sections
+
+## Loading patterns
+
+| Wait | Pattern |
+|---|---|
+| < 200ms | No indicator |
+| 200-1000ms | Subtle skeleton or muted spinner |
+| > 1000ms | Skeleton with shape, optional progress bar |
+| > 5000ms | Status text + progress bar |
+| User-initiated long task | Indeterminate -> determinate progress, ETA if known |
+
+## Have-Nots
+
+You fail motion if:
+
+- `prefers-reduced-motion` not honored
+- Bounce/elastic easing on production UI
+- Animation duration > 500ms for non-page-level transitions
+- Slow exits (> 200ms) on dismissable elements
+- Decorative motion without intent
+- Stagger applied to > 10 items

package/references/design/RESPONSIVE.md

@@ -0,0 +1,157 @@
+# Responsive Design
+
+> Godpowers' baseline guidance for breakpoints, fluid design, and mobile.
+> Shallower than
+> [Impeccable's responsive-design reference](https://github.com/pbakaus/impeccable/blob/main/skill/reference/responsive-design.md).
+
+## Mobile-first, always
+
+Write the smallest screen first. Add media queries to scale up.
+
+```css
+/* default: mobile */
+.container { padding: 16px; font-size: 1rem; }
+
+@media (min-width: 768px) {
+  .container { padding: 32px; font-size: 1.125rem; }
+}
+
+@media (min-width: 1280px) {
+  .container { padding: 64px; font-size: 1.25rem; }
+}
+```
+
+Don't default to desktop and reverse. Mobile-first compresses better
+for the small majority.
+
+## Breakpoints
+
+Pick three. More than three is decoration; fewer is a missed
+opportunity.
+
+| Name | Min | Targets |
+|---|---|---|
+| `sm` | 640px | Large phones, small tablets |
+| `md` | 768px | Tablets |
+| `lg` | 1024px | Small laptops |
+| `xl` | 1280px | Most laptops, monitors |
+| `2xl` | 1536px | Large monitors |
+
+Recommended starter trio: `768px`, `1024px`, `1280px`. Add others only
+when content demands.
+
+## Container queries (when supported)
+
+Modern browsers support `@container`. Use when components need to
+adapt based on their parent's width, not the viewport's:
+
+```css
+.card-list { container-type: inline-size; }
+
+@container (min-width: 600px) {
+  .card { display: grid; grid-template-columns: 200px 1fr; }
+}
+```
+
+Better than viewport queries for component libraries that ship in
+varied contexts.
+
+## Fluid type and spacing
+
+Use `clamp()` to interpolate between breakpoints:
+
+```css
+.heading {
+  font-size: clamp(1.5rem, 1rem + 2vw, 3rem);
+  /* min 1.5rem, scales with viewport, caps at 3rem */
+}
+```
+
+This collapses three media queries into one declaration. Type stops
+being staircased.
+
+## Touch targets
+
+iOS HIG: 44x44px minimum.
+Android Material: 48x48px minimum.
+
+Use 48x48px or larger for primary actions. Smaller targets fail tap
+tests for users with motor impairments.
+
+```css
+.button { min-height: 48px; min-width: 48px; padding: 0 16px; }
+```
+
+Apply to icon-only buttons especially. A 24px icon + 12px padding all
+sides = 48x48 hit target.
+
+## Anti-patterns
+
+- **Hover-only interactions.** Touch devices have no hover. Anything
+  triggered by hover must also be reachable by tap.
+- **Hidden mobile content.** "Show on desktop only" loses critical
+  information. If desktop has it, mobile needs it (possibly
+  reorganized, never disappeared).
+- **Tiny text scales.** `font-size: 11px` on body is unreadable on
+  mobile. Minimum 14px, typically 16px.
+- **Horizontal scroll on mobile.** Always a bug unless explicitly
+  designed (carousel).
+- **Fixed pixel widths.** Use rems, percentages, or CSS Grid. Fixed
+  px breaks at unusual viewports.
+
+## Common layouts that adapt
+
+### Grid that flows
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 24px;
+}
+```
+
+This auto-collapses to fewer columns as the viewport narrows. No media
+queries needed.
+
+### Hero that re-flows
+
+```css
+.hero {
+  display: flex;
+  flex-direction: column;     /* mobile: stacked */
+  gap: 32px;
+}
+
+@media (min-width: 768px) {
+  .hero { flex-direction: row; align-items: center; }
+}
+```
+
+### Navigation that collapses
+
+Mobile: hamburger or bottom-tab bar.
+Tablet: condensed top nav.
+Desktop: full top nav with all items visible.
+
+Use `<nav>` with semantic markup; let CSS hide/show variants. Avoid
+duplicating navigation structure for breakpoints.
+
+## Dark mode + responsive
+
+Test both: dark mode on mobile and dark mode on desktop. Light
+backgrounds at small sizes can be glaring; dark variants tend to feel
+more natural on phones at night.
+
+## Have-Nots
+
+You fail responsive if:
+
+- Body font < 14px on mobile
+- Hover-only interactions exist
+- Touch targets < 44x44px
+- Horizontal scroll appears on screens >= 320px
+- Mobile loses content that desktop has
+- Breakpoints scattered randomly (not on the chosen scale)
+- Components use viewport queries when container queries are appropriate
+- Fixed-px widths in layout containers

package/references/design/SPATIAL.md

@@ -0,0 +1,109 @@
+# Spatial Design
+
+> Godpowers' baseline guidance for spacing, grids, and rhythm.
+> Shallower than
+> [Impeccable's spatial-design reference](https://github.com/pbakaus/impeccable/blob/main/skill/reference/spatial-design.md).
+
+## Pick one spacing scale, use it everywhere
+
+Match the typography ratio. If your type uses 1.25 (Major Third), use
+the same for spacing:
+
+```yaml
+spacing:
+  xs: 8px
+  sm: 12px       # 8 * 1.25^1
+  md: 16px       # 8 * 1.25^2  (rounded)
+  lg: 24px       # 8 * 1.25^3.5 (rounded to grid)
+  xl: 32px
+  2xl: 48px
+  3xl: 64px
+```
+
+Powers-of-2 friendly values (8, 16, 24, 32, 48, 64) are good defaults
+because they hit common breakpoints and feel anchored.
+
+## Anti-patterns
+
+- **Random px values** (13px, 17px, 22px). The reader can't tell, but
+  the system feels noisy. Stick to the scale.
+- **Cards-in-cards-in-cards.** Wrap once. Twice if structurally needed.
+  Three times means you're nesting visual containers to hide a layout
+  problem.
+- **Same padding everywhere.** Buttons, cards, and sections need
+  different breathing room. Tokenize: `padding-button: md`,
+  `padding-card: lg`, `padding-section: 3xl`.
+- **Cramped touch targets.** Mobile minimum: 44x44px. UI buttons under
+  that fail accessibility heuristics.
+- **Inconsistent vertical rhythm.** All baselines should snap to a
+  multiple of 4px or 8px.
+
+## Grid
+
+Pick a grid that matches content density:
+
+| Density | Columns | Gutter | Use |
+|---|---|---|---|
+| Marketing | 12 | 24-32px | Long-form, varied content |
+| Product | 8-10 | 16-24px | Tables, dashboards, lists |
+| Editorial | 6 | 24-40px | Reading, articles |
+| Single-column | 1 | n/a | Narrow product, mobile-first |
+
+Containers cap at:
+
+- 1280-1440px for product UI
+- 720-960px for reading content
+- 480-640px for forms, focused tasks
+
+Wider than 1440px feels theatrical. Narrower than 480px crowds.
+
+## Whitespace philosophy
+
+Whitespace is a primary layout tool, not "what's left over."
+
+- **Breathing room around blocks**: 2-4x the line-height
+- **Adjacent unrelated sections**: 4-8x the line-height
+- **Tight related elements**: 0.5-1x the line-height (icon + label,
+  caption + image)
+- **Padding inside containers**: matches the outer rhythm; 16-32px is
+  the typical band
+
+The eye reads grouped elements as related. Gestalt's law of proximity
+does layout for you if you let it.
+
+## Container padding
+
+Default rule: container padding equals or exceeds the largest gap
+between children. If children sit 24px apart, container padding is at
+least 24px.
+
+```css
+.section { padding: 64px 32px; }       /* 64 vert, 32 horiz */
+.card    { padding: 24px; }
+.cta-box { padding: 32px 24px; }
+.button  { padding: 12px 20px; }
+```
+
+## Vertical rhythm
+
+Section spacing dominates the page feel:
+
+```
+Tight:    32-48px between sections
+Default:  64-96px
+Generous: 96-160px
+```
+
+Mismatched section spacing reads as "designed in pieces." Keep it
+consistent within a page.
+
+## Have-Nots
+
+You fail spatial if:
+
+- Random px values not on the scale (e.g., 13, 17, 21, 27)
+- Touch targets < 44x44px
+- Cards nested 3+ levels deep
+- Section spacing inconsistent within a page (>20% variance)
+- Container padding < largest inner gap
+- More than 3 distinct grid systems in one project

package/references/design/TYPOGRAPHY.md

@@ -0,0 +1,121 @@
+# Typography
+
+> Godpowers' baseline guidance for type. Shallower than
+> [Impeccable's typography reference](https://github.com/pbakaus/impeccable/blob/main/skill/reference/typography.md);
+> use this when Impeccable isn't installed. Our opinions, not theirs.
+
+## Pick at most two type families
+
+Most projects need exactly two: a **display** family for headlines and a
+**body** family for paragraphs and UI. A third, monospace family for
+code or numerics is fine. Beyond three, the system fragments.
+
+### Recommended pairings
+
+| Register | Display | Body | Why |
+|---|---|---|---|
+| Editorial / serious | Fraunces, Newsreader, Instrument Serif | Inter, Söhne, system-ui | Serif gravity + sans clarity |
+| Software / product | Geist, Söhne, Inter | Inter, system-ui | Single sans family at varying weights |
+| Brand / playful | Cabinet Grotesk, Mona Sans | Inter, Söhne | Geometric display + neutral body |
+| Technical / docs | IBM Plex Sans / Mono | IBM Plex Sans | One family across roles |
+
+## Anti-patterns
+
+- **Inter for everything.** It's a fine body face; using it for display
+  flattens hierarchy. Pair it with a display face you actually pick.
+- **System default fallback chains in production.** `system-ui` is fine
+  in dev; ship a real loaded face for display.
+- **Five weights of one family used randomly.** Pick three weights:
+  body (400), strong (500/600), display (600/700). Stop there.
+- **Letter-spacing larger than 0.05em on body text.** Reads like a
+  headline; tires the eye.
+- **Italic for emphasis on UI elements.** Use weight (or color); italic
+  belongs in editorial copy.
+
+## Modular scale
+
+Use a ratio, not arbitrary px values. Common ratios:
+
+| Ratio | Name | Feel |
+|---|---|---|
+| 1.125 | Major Second | Very tight, technical |
+| 1.200 | Minor Third | Compact, dense UI |
+| 1.250 | Major Third | Balanced, common default |
+| 1.333 | Perfect Fourth | Editorial, generous |
+| 1.500 | Perfect Fifth | Marketing, dramatic |
+
+Pick one. Apply to your spacing scale too (Spatial reference).
+
+### Practical scale (1.250)
+
+```
+xs:    0.75rem   12px
+sm:    0.875rem  14px
+base:  1rem      16px
+lg:    1.25rem   20px
+xl:    1.5rem    24px
+2xl:   1.875rem  30px
+3xl:   2.5rem    40px
+4xl:   3.75rem   60px
+```
+
+## Line height
+
+| Use | Line height |
+|---|---|
+| Display (>32px) | 1.05-1.15 |
+| Headline (24-32px) | 1.2-1.3 |
+| Body (14-18px) | 1.5-1.65 |
+| Dense UI / labels | 1.3-1.4 |
+
+Display lines look broken at 1.5; body lines look cramped at 1.2.
+
+## Tabular numerals
+
+Always enable for numeric columns and tables:
+
+```css
+font-feature-settings: "tnum";
+```
+
+Or in your DESIGN.md typography token:
+
+```yaml
+typography:
+  numeric:
+    fontFamily: Inter
+    fontSize: 2.5rem
+    fontFeature: tnum
+```
+
+Without `tnum`, columns of numbers wobble.
+
+## OpenType features worth using
+
+| Feature | When |
+|---|---|
+| `tnum` | Tables, columns, dashboards |
+| `case` | All-caps text; aligns punctuation |
+| `salt` | Designer-chosen alternates (single-storey 'a', etc.) |
+| `liga` | Standard ligatures (default in most browsers) |
+| `kern` | Pair kerning (default in modern browsers) |
+
+## Loading
+
+- Self-host `.woff2` whenever possible. Google Fonts is fine; their
+  CDN adds latency and a third-party request.
+- `font-display: swap` for body, `optional` for display (avoid FOIT).
+- Subset to the characters you actually use. A full Latin face is
+  ~100KB; a subset can be 20KB.
+
+## Have-Nots
+
+You fail typography if:
+
+- More than 2 families in use (3 if monospace counts; do not exceed 3)
+- Letter-spacing > 0.05em on body
+- Italic used for UI emphasis
+- No tabular numerals on table columns
+- Body line-height < 1.4 or > 1.7
+- Display line-height > 1.2
+- All five weights of the same family in active use

package/references/design/UX-WRITING.md

@@ -0,0 +1,135 @@
+# UX Writing
+
+> Godpowers' baseline guidance for product copy. Shallower than
+> [Impeccable's ux-writing reference](https://github.com/pbakaus/impeccable/blob/main/skill/reference/ux-writing.md).
+
+## Write for the person doing the task
+
+Every word in the UI should serve the next action. If a button says
+"Submit," the user has to translate that to "submit what?" If it says
+"Send invoice," they don't.
+
+## Buttons: verb-noun, never "click here"
+
+| Bad | Better |
+|---|---|
+| Click Here | View invoice |
+| OK | Save changes |
+| Submit | Send invitation |
+| Cancel | Discard changes |
+| Yes | Confirm delete |
+
+The button labels its outcome, not the user's gesture.
+
+## Empty states: name the next action
+
+| Bad | Better |
+|---|---|
+| No data. | No invoices yet. Connect Stripe to import. |
+| Empty list. | Nothing in your queue. Add a task to get started. |
+| Loading... | Loading your dashboard... |
+
+Empty states are onboarding opportunities, not error states.
+
+## Error messages: 3 rules
+
+1. **Be specific.** "Invalid input" is useless. "Email needs an @
+   symbol" is actionable.
+2. **Be forward-looking.** Tell them what to do, not what they
+   did wrong. "Try a longer password" beats "Password too short."
+3. **Avoid blame.** "We couldn't reach Stripe" is better than "You
+   entered an invalid Stripe key."
+
+### Status codes by user-facing severity
+
+| Code | User sees |
+|---|---|
+| 4xx (user error) | Specific, fixable, actionable |
+| 5xx (our error) | "Something went wrong on our end. Try again, or contact support." |
+| Network failure | "Lost connection. Check your network and retry." |
+| Validation | Inline, near the field |
+
+Never show a stack trace or raw error code in production UI.
+
+## Numbers and dates
+
+- **Dates**: relative for recent ("3 days ago"), absolute for far
+  ("March 15, 2026").
+- **Times**: include timezone unless the user's local context is
+  obvious. "9:00 AM ET" not "9:00 AM."
+- **Money**: always with currency symbol AND code on first reference
+  ("$50 USD"). Subsequent refs can drop the code.
+- **Counts**: pluralize correctly. "1 invoice" / "12 invoices."
+  Internationalize for non-English locales.
+
+## Pronouns
+
+- **Second person ("you")** for instructions: "Click here to verify
+  your email."
+- **First person ("I", "we")** for product voice or reflective
+  statements: "We'll send you a receipt." / "I want to delete this."
+- **Avoid third person** in product UI: "The user can configure..."
+  feels like a manual.
+
+## Tone calibration
+
+| Project type | Tone |
+|---|---|
+| Productivity / serious | Direct, terse, no exclamation marks |
+| Creative / playful | Conversational, occasional warmth, light wit |
+| Healthcare / financial | Calm, precise, never urgent unless truly is |
+| Developer tools | Technical, dense, can use jargon if appropriate |
+
+Pick one. Mismatched tone within a single product reads as
+inconsistent.
+
+## Anti-patterns
+
+- **Exclamation overload.** "Welcome! Sign in! Get started!" reads as
+  fake enthusiasm. Use exclamations sparingly: success messages,
+  achievements, intentional surprise.
+- **"Awesome" / "Sweet" / "Boom".** Friendly tone gone too casual.
+  Tells the reader the team is trying too hard.
+- **All caps for emphasis.** Reads as shouting. Use weight or color.
+- **Jargon without explanation.** "OAuth flow failed" means nothing to
+  most users. "We couldn't connect to Stripe; please try logging in
+  again."
+- **Long form labels.** "What is your favorite color?" inside a label
+  is a question, not a label. Use "Favorite color" + helper text below.
+
+## Microcopy templates
+
+### Confirmation
+
+> Delete invoice? This cannot be undone.
+> [Cancel] [Delete]
+
+### Destructive action
+
+> You're about to delete the production database.
+> Type `delete-production` to confirm.
+
+### Success
+
+> Saved. (toast, dismisses after 4s)
+
+### Loading (long task)
+
+> Generating your report. We'll email you when it's ready.
+
+### Onboarding
+
+> Welcome to MRR Tracker. Let's connect your first Stripe account.
+> [Connect Stripe]
+
+## Have-Nots
+
+You fail UX writing if:
+
+- Buttons say "Click here," "Submit," "OK," "Cancel" generically
+- Error messages don't tell the user what to do
+- Empty states don't suggest a next action
+- Dates have no timezone
+- Money values lack currency code on first reference
+- Stack traces or raw error codes shown in production
+- Tone shifts within the same product (jokey signup, terse settings)