@jaimevalasek/aioson 1.4.0 → 1.5.1

package/template/.aioson/skills/design/cognitive-core-ui/references/websites.md

@@ -35,6 +35,65 @@ A commercial page using this skill should feel **premium and technical, but stil
 
 ---
 
+## Website Composition Library
+
+Choose one primary composition before building sections. Do not default to the same centered hero every time.
+
+### 1. Split Narrative
+
+Use when:
+- the product needs both message and visual proof above the fold
+
+Composition:
+- headline and CTA on one side
+- product frame, screenshot, or visual artifact on the other
+- secondary proof rail below
+
+### 2. Editorial Stack
+
+Use when:
+- the brand needs intelligence, depth, or cultural weight
+
+Composition:
+- offset headline
+- side notes, quote blocks, or pull metrics
+- more asymmetry, more narrative rhythm
+
+### 3. Proof-First
+
+Use when:
+- credibility matters more than storytelling flourish
+
+Composition:
+- immediate outcomes, metrics, logos, or customer proof near the hero
+- product explanation follows
+
+### 4. Product Theater
+
+Use when:
+- the interface itself is the main differentiator
+
+Composition:
+- immersive product frame
+- layered caption rails
+- supporting sections explain workflows and advantages
+
+### 5. Institutional Precision
+
+Use when:
+- the site must feel trustworthy, executive, and polished
+
+Composition:
+- concise hero
+- structured value blocks
+- case study or trust strip
+- elegant CTA instead of hype-heavy spectacle
+
+Rule:
+- pick one composition and one signature move from `references/art-direction.md`, then propagate them intentionally
+
+---
+
 ## Default theme for websites
 
 - **Light theme**: Institutional sites, corporate, marketing pages, client-facing products
@@ -55,7 +114,7 @@ If the user does not specify, use **dark with a light option toggle** for tech/S
 │  HERO SECTION (padding: space-24 top, space-20 bottom) │
 │  ┌──────────────────────────────────────────────────┐  │
 │  │ MONO LABEL: tagline (centered)                   │  │
-│  │ DISPLAY HEADING text-5xl, weight-black (centered)│  │
+│  │ DISPLAY HEADING text-5xl, weight-bold (centered) │  │
 │  │ Subtitle: text-lg, text-secondary (centered)     │  │
 │  │ [CTA Primary Button]  [Secondary Button]         │  │
 │  └──────────────────────────────────────────────────┘  │
@@ -85,12 +144,15 @@ If the user does not specify, use **dark with a light option toggle** for tech/S
 
 ### Hero section (required elements)
 
-1. **Mono label** above heading — category / tagline in monospace uppercase
-2. **Display heading** — `text-5xl`, `weight-black`, `tracking-tight`, `line-height: 1.1`
+1. **Mono label** above heading — category / tagline in monospace uppercase, used sparingly
+2. **Display heading** — `text-5xl`, `weight-bold` or `weight-black` only when the hero truly needs extra emphasis, `tracking-tight`, `line-height: 1.1`
 3. **Subtitle** — 1–2 sentences, `text-lg`, `text-secondary`
 4. **Two CTAs** — primary (solid accent) + secondary (outline or ghost)
 5. **Optional**: hero visual (screenshot, illustration, or abstract mesh)
 
+Hero rule:
+- If the page would benefit from split, editorial, or proof-first composition, do not force all five elements into a centered stack.
+
 ```css
 .hero {
   min-height: 90vh; display: flex; align-items: center; justify-content: center;
@@ -108,7 +170,7 @@ If the user does not specify, use **dark with a light option toggle** for tech/S
 }
 .hero-heading {
   font-family: var(--font-display); font-size: var(--text-5xl);
-  font-weight: var(--weight-black); color: var(--text-heading);
+  font-weight: var(--weight-bold); color: var(--text-heading);
   letter-spacing: var(--tracking-tight); line-height: 1.05;
   margin-bottom: var(--space-5);
 }
@@ -142,7 +204,7 @@ If the user does not specify, use **dark with a light option toggle** for tech/S
 }
 .section-heading {
   font-family: var(--font-display); font-size: var(--text-3xl);
-  font-weight: var(--weight-black); color: var(--text-heading);
+  font-weight: var(--weight-bold); color: var(--text-heading);
   letter-spacing: var(--tracking-tight); line-height: var(--leading-tight);
 }
 ```
@@ -303,12 +365,13 @@ Two columns: [Left: contact info cards] [Right: form card]
 Primary CTA button:
 ```css
 .btn-primary {
-  background: var(--accent); color: var(--bg-base);
-  font-family: var(--font-mono); font-size: var(--text-sm);
+  background: var(--accent); color: var(--accent-contrast);
+  font-family: var(--font-body); font-size: var(--text-sm);
   font-weight: var(--weight-semibold); letter-spacing: var(--tracking-wide);
-  text-transform: uppercase; padding: var(--space-3) var(--space-6);
+  text-transform: none; padding: var(--space-3) var(--space-6);
+  min-height: var(--control-md);
   border-radius: var(--radius-md); border: none; cursor: pointer;
-  transition: var(--transition-base);
+  transition: var(--transition-base), transform 150ms ease, box-shadow 150ms ease;
   box-shadow: 0 0 20px var(--accent-glow);
 }
 .btn-primary:hover {
@@ -316,6 +379,10 @@ Primary CTA button:
   box-shadow: 0 0 32px var(--accent-glow), 0 4px 12px rgba(0,0,0,0.2);
   transform: translateY(-1px);
 }
+.btn-primary:focus-visible {
+  outline: var(--focus-ring-width) solid var(--accent);
+  outline-offset: var(--focus-ring-offset);
+}
 ```
 
 Secondary button:
@@ -323,18 +390,29 @@ Secondary button:
 .btn-secondary {
   background: transparent; color: var(--text-primary);
   border: 1px solid var(--border-medium);
-  font-family: var(--font-mono); font-size: var(--text-sm);
+  font-family: var(--font-body); font-size: var(--text-sm);
   font-weight: var(--weight-semibold); letter-spacing: var(--tracking-wide);
-  text-transform: uppercase; padding: var(--space-3) var(--space-6);
+  text-transform: none; padding: var(--space-3) var(--space-6);
+  min-height: var(--control-md);
   border-radius: var(--radius-md); cursor: pointer;
-  transition: var(--transition-base);
+  transition: var(--transition-base), transform 150ms ease;
 }
 .btn-secondary:hover {
+  background: var(--accent-subtle);
   border-color: var(--border-accent);
   color: var(--accent);
 }
+.btn-secondary:focus-visible {
+  outline: var(--focus-ring-width) solid var(--accent);
+  outline-offset: var(--focus-ring-offset);
+}
 ```
 
+Guardrails:
+- Do not use `color: var(--bg-base)` for accent buttons in light theme.
+- Default website CTAs should read like polished product buttons, not terminal labels.
+- If uppercase mono is desired for branding reasons, keep the label very short and re-check contrast in hover/focus states.
+
 ---
 
 ## Key differences: dashboard vs website
@@ -348,3 +426,12 @@ Secondary button:
 | Cards | Dense, compact | Spacious, feature-oriented |
 | Navigation | Tab-heavy, sidebar | Linear anchors, single bar |
 | Background alternation | Same bg-base | Alternates `bg-base` / `bg-surface` |
+
+---
+
+## Anti-Generic Website Rules
+
+- Do not repeat the same section rhythm from top to bottom.
+- Do not rely on centered text alone to create impact.
+- Use at least one memorable section transition, composition break, or proof rail.
+- If the page looks like "SaaS template with nicer colors", it is not finished.

package/template/.aioson/skills/design/warm-craft-ui/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: warm-craft-ui
+description: Warm Craft UI is a design system for approachable, human-centered interfaces with light backgrounds, rounded forms, warm accents, generous whitespace, and humanist typography. Use it when `design_skill: warm-craft-ui` is set in project.context.md OR when the user explicitly asks for "warm", "friendly UI", "clean light", "soft modern", "human-centered", "Notion-like", "Linear-like", "calm interface", or similar. Ideal for productivity apps, SaaS B2C, health, education, personal finance, and any product where trust, clarity, and approachability matter more than density or authority. Supports apps, dashboards, landing pages, and websites — light by default with an optional dark theme. Do NOT use this skill unless explicitly selected.
+---
+
+# Warm Craft UI
+
+A design system where **clarity is generosity and whitespace is confidence**. Warm Craft sits at the intersection of humanist typography and disciplined spacing — interfaces that feel handcrafted, breathable, and immediately trustworthy.
+
+**This is one visual system.** Never combine it with another design skill.
+
+## Package structure
+
+```text
+.aioson/skills/design/warm-craft-ui/
+  SKILL.md                      <- you are here (load this first)
+  references/
+    art-direction.md            <- intent, domain exploration, expression modes, signature moves, anti-generic tests
+    design-tokens.md            <- CSS variables light + dark, typography, token scope guardrails
+    components.md               <- All reusable components (nav, cards, forms, tables, badges, modals, etc.)
+    patterns.md                 <- Page layouts: app shell, detail, settings, onboarding, list-detail
+    dashboards.md               <- Dashboard presets: overview, analytics, activity feed, project board, admin
+    websites.md                 <- Landing page, product page, institutional layouts + anti-patterns
+    motion.md                   <- Animations: entrances, micro-interactions, scroll, loading states
+```
+
+## Activation rules
+
+- Apply this package **only** when `project.context.md` contains `design_skill: "warm-craft-ui"` or the user explicitly chooses it.
+- If another design skill is selected, do **not** load this package.
+- Never auto-select this skill — always require explicit confirmation.
+- If no skill is set yet, the active agent must ask or confirm before applying.
+
+## Responsibility boundary
+
+This skill defines:
+- Visual direction and aesthetic DNA
+- Design tokens (colors, typography, spacing, radius, shadows)
+- Component vocabulary and anatomy
+- Page composition patterns
+- Theme switching behavior (light/dark)
+
+This skill does **not** decide:
+- Stack (React, Vue, Blade, HTML, etc.)
+- Output format (single file, multi-file, CSS modules, Tailwind, etc.)
+- Icon library choice
+- Whether a theme toggle exists in the product (the agent decides)
+
+## Loading guide
+
+Always load only what the current task needs:
+
+| Task | Load |
+|---|---|
+| Any UI work | `references/design-tokens.md` |
+| Reusable components | `references/design-tokens.md` + `references/components.md` |
+| Dashboard or admin panel | `references/art-direction.md` + `references/design-tokens.md` + `references/components.md` + `references/patterns.md` + `references/dashboards.md` |
+| Detail / settings page | `references/art-direction.md` + `references/design-tokens.md` + `references/components.md` + `references/patterns.md` |
+| Landing page or website | `references/art-direction.md` + `references/design-tokens.md` + `references/components.md` + `references/websites.md` |
+| Motion / animation | add `references/motion.md` when animation materially improves the result |
+| Full UI build | all seven reference files |
+
+## Visual signature — three pillars
+
+1. **Approachable warmth** — Light surfaces with subtle warm undertones. Rounded corners on everything. Colors that feel like sunlight through linen, not clinical LED panels. The interface should feel like a well-designed physical notebook, not a control room.
+2. **Typographic humanity** — Humanist sans-serif with visible character. Generous line-heights. Text that breathes. Headings that feel handwritten in their weight and tracking, even though they are perfectly set. Body text that is genuinely pleasant to read for long sessions.
+3. **Disciplined calm** — Generous whitespace that signals confidence, not emptiness. One accent color used sparingly. Subtle depth through soft shadows, not hard borders. Every element has room to exist without competing for attention.
+
+## Theme system
+
+```html
+<div data-theme="light">   <!-- or data-theme="dark" -->
+```
+
+- **Light (default)**: Productivity apps, content platforms, B2C SaaS, health, education, personal tools, most use cases
+- **Dark**: Optional — for users who prefer it, night modes, media-heavy contexts
+- **Both with toggle**: When the user asks, or when the product serves diverse contexts
+
+If the user does not specify: default to **light with a theme toggle** available.
+
+## Visual DNA
+
+### Colors — light theme
+- Background void: `#F8F6F3` (warm off-white, never pure #FFF)
+- Background base: `#FDFCFA` (main app background)
+- Surface: `#FFFFFF` (cards, elevated panels)
+- Elevated: `#F3F1ED` (hover, nested, sidebar backgrounds)
+- Primary accent: `#E07A5F` (terracotta/warm coral) — CTAs, active states, key highlights
+- Text heading: `#2D3436` (warm charcoal, never pure black)
+- Text primary: `#4A5568` (readable warm gray)
+- Text secondary: `#8896A6` (muted)
+- Text muted: `#B0BCC7` (hints, placeholders)
+
+### Colors — dark theme
+- Background void: `#1A1814` (warm dark, not navy)
+- Background base: `#211F1B` (main app background)
+- Surface: `#2A2824` (cards)
+- Elevated: `#353330` (hover, nested)
+- Primary accent: `#F0967D` (lighter terracotta for dark backgrounds)
+- Text heading: `#F5F0EB`
+- Text primary: `#D4CBC2`
+- Text secondary: `#9A9088`
+- Text muted: `#6B6460`
+
+### Typography
+- Headings: `Source Serif 4`, `weight-semibold (600)` or `weight-bold (700)` for page titles, `letter-spacing: -0.02em`
+- Body: `Inter`, `weight-normal (400)`, `line-height: 1.7`
+- Labels and metadata: `Inter`, `weight-medium (500)`, `font-size: 0.8rem`, `letter-spacing: 0.02em`
+- Stats: `Source Serif 4`, `weight-bold (700)`, `font-size: 2.5rem`
+
+### Layout structure (apps)
+```
++----------------------------------------------------------+
+|  TOP BAR: [Logo] [Search (center, rounded)]  [Avatar]    |
++----------------------------------------------------------+
+|           |                                               |
+|  SIDEBAR  |  CONTENT                                      |
+|  200px    |  PAGE HEADER (serif title + subtitle)         |
+|  soft bg  |                                               |
+|  rounded  |  CONTENT SECTIONS                             |
+|  items    |  (generous padding, card groups)              |
+|           |                                               |
+|  [nav     |  SECTION: title + description                 |
+|   items   |  CARD GROUP (2-3 col, gap-6)                 |
+|   with    |                                               |
+|   icons]  |  SECTION: title + description                 |
+|           |  CARD GROUP or TABLE                          |
++-----------+-----------------------------------------------+
+```
+
+### Signature details
+- Rounded corners on everything: cards `radius-xl` (16px), buttons `radius-lg` (12px), inputs `radius-md` (8px)
+- Soft shadows: `box-shadow` with warm tones, never harsh black drops
+- Accent used sparingly: primary buttons, active nav, key badges — never borders, never backgrounds of sections
+- Serif headings mixed with sans-serif body — the primary differentiator from every other UI
+- Subtle background patterns: very faint dot grid or warm gradient wash on hero sections
+- Illustrations and empty states: warm, hand-drawn style — never cold geometric
+- Input fields: visible but soft borders, generous padding, rounded
+- Active sidebar item: `background: var(--bg-elevated)` + `border-radius: var(--radius-lg)` + accent text — no hard left border
+- Theme transition: `200ms ease` on background, color, border-color, box-shadow
+
+## Application rules
+
+- Treat `references/design-tokens.md` as the source of truth for ALL tokens.
+- Treat `references/art-direction.md` as the source of truth for expression, signature moves, and anti-generic decisions.
+- Resolve the page variant before composing: apps use structured navigation rhythm; websites/landing pages use more narrative flow, larger typography, and editorial pacing.
+- Never combine this package with `cognitive-core-ui`, `interface-design`, `premium-command-center-ui`, or any other design skill in the same task.
+- Reuse the project's component library if one exists — map Warm Craft tokens onto it instead of rebuilding primitives.
+- Adapt code examples to the active stack. Reference snippets are design specifications, not copy-paste code.
+- Accessibility, responsiveness, and production semantics are the agent's responsibility (not this skill).
+
+## Intent before visuals
+
+Before choosing layout, answer all three:
+
+1. Who is the human using this page right now?
+2. What is the main action or decision they must complete?
+3. How should this interface feel in concrete words, not generic labels?
+
+Bad answers:
+- "for users"
+- "manage content"
+- "clean and modern"
+
+Good answers:
+- "freelancer reviewing today's tasks over morning coffee"
+- "parent checking their child's learning progress after dinner"
+- "calm, warm, spacious, like a well-organized desk with natural light"
+
+## Workflow discipline
+
+1. Audit the current page or existing UI before changing visuals.
+2. Explore the product domain and choose one expression mode from `references/art-direction.md`.
+3. Name one signature move and repeat it intentionally across the page.
+4. Consolidate repeating patterns instead of inventing new card/button/table variants for each screen.
+5. Build from tokens first, then components, then page composition.
+6. Validate state parity before finishing: default, hover, active, focus, disabled.
+7. Validate contrast before shipping: body text must meet WCAG AA, controls must stay legible in all themes and states.
+
+## Non-negotiable quality gates
+
+- Never use pure white (#FFFFFF) as the app background — always use warm off-whites.
+- Never use pure black (#000000) for text — always warm charcoals.
+- Never crowd elements — when in doubt, add more whitespace, not more content.
+- Serif headings are the signature — never replace them with sans-serif across the board.
+- Accent must feel warm, never clinical or cold (no blues, no purples as primary).
+- Rounded corners are structural, not decorative — everything is rounded, consistently.
+- Soft shadows must use warm-tinted RGBA, not generic `rgba(0,0,0,...)`.
+- Forms must feel inviting: generous padding, visible labels above fields, helpful placeholders — never cramped.
+- Hardcoded colors, arbitrary sharp corners, and one-off font choices are design-system failures.
+- Sameness is failure. If the result could be mistaken for a default Notion clone or a generic SaaS template, iterate before presenting.
+- Every full page must have one memorable structural or visual signature, not just "good spacing and cards".
+- Do not reuse the same hero, card layout, or dashboard grid across unrelated products without a domain reason.
+
+## Delivery modes
+
+### Greenfield
+1. Choose page variant (app, detail, settings, landing, institutional)
+2. Load relevant references
+3. Apply token scope from `design-tokens.md`
+4. Compose layout from `patterns.md` or `websites.md`
+5. Build components from `components.md`
+
+### Brownfield
+1. Audit existing UI before rewriting
+2. Map Warm Craft tokens onto the existing component library
+3. Fix token scope issues (font/color variables must be on the correct container)
+4. Consolidate duplicate variants before introducing new ones
+5. Prefer targeted upgrades over full rewrites unless the user asks for a redesign