@jaimevalasek/aioson 1.4.0 → 1.6.0

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

package/template/.aioson/skills/design/warm-craft-ui/references/art-direction.md

@@ -0,0 +1,324 @@
+# Art Direction — Warm Craft UI
+
+Read this file for any page-level work where differentiation matters: apps, dashboards, landing pages, websites, profile pages, and major flows.
+
+This file exists to stop Warm Craft from collapsing into the same light rounded-card layout every time.
+
+The system stays coherent, but the expression must change with the product, the user, and the dominant task.
+
+---
+
+## Core Rule
+
+**Same warmth, different character.**
+
+Keep the Warm Craft DNA:
+- warm-toned surfaces and soft depth
+- humanist typography with serif headings
+- generous whitespace as a design principle
+- rounded, approachable forms
+
+But do **not** keep the exact same composition, hero, card rhythm, or visual emphasis from project to project.
+
+---
+
+## Mandatory Pre-Build Outputs
+
+Before designing a full page, produce all of these:
+
+1. **Human**
+   The real person using this page right now.
+
+2. **Main action**
+   The one decision, action, or question that matters most on this screen.
+
+3. **Felt quality**
+   Concrete emotional words such as `warm`, `spacious`, `trustworthy`, `crafted`, `calm`, `inviting`, `focused`, `playful`, `gentle`, `grounded`.
+   Never use empty labels like `clean`, `modern`, or `beautiful`.
+
+4. **Domain vocabulary**
+   At least 5 concepts from the product's world.
+   Example for a learning app: `lesson`, `streak`, `milestone`, `practice`, `mastery`.
+
+5. **Material world**
+   At least 5 materials or textures that belong to that product world.
+   Example: warm paper, natural wood, linen cloth, clay, dried flowers, leather notebook, morning sunlight.
+
+6. **Defaults to avoid**
+   Name 3 obvious UI choices that would make the result generic.
+
+7. **Signature move**
+   One memorable design move that can appear in at least 5 places on the page.
+
+If you cannot do these seven, you are not ready to compose the page.
+
+---
+
+## Expression Modes
+
+Choose **one primary mode** per screen. You may borrow a small amount from a secondary mode only after the main expression is clear.
+
+### 1. Morning Desk
+
+Use for:
+- productivity apps
+- task managers
+- personal dashboards
+- note-taking tools
+- CRM for small teams
+
+Feel:
+- organized
+- spacious
+- focused
+- like opening a clean notebook
+
+Composition:
+- clear content zones with generous breathing room
+- one dominant action area above the fold
+- sidebar as quiet companion, not attention-grabber
+- cards as containers, not decoration
+
+Visual cues:
+- warm white backgrounds with barely-there warm tint
+- soft card shadows that suggest depth without shouting
+- serif headings that ground the hierarchy
+- accent used only on the primary action
+
+Signature ideas:
+- oversized greeting header with user context ("Good morning, Sarah. 3 tasks today.")
+- card with subtle left border accent for priority items
+- inline progress indicator with warm fill animation
+
+### 2. Sunlit Studio
+
+Use for:
+- creative tools
+- design platforms
+- portfolio builders
+- content creation apps
+- media management
+
+Feel:
+- inspiring
+- creative
+- warm but vibrant
+- like a well-lit art studio
+
+Composition:
+- larger visual elements and media previews
+- asymmetric layouts that feel curated, not random
+- generous negative space around focal content
+- playful grid that rewards browsing
+
+Visual cues:
+- accent color used more expressively (subtle background washes, not just buttons)
+- more pronounced shadow depth for media cards
+- type mixing as creative expression: serif titles, sans body, occasional italic
+- rounded containers that feel like frames
+
+Signature ideas:
+- gallery grid with hover-reveal metadata
+- hero media card with editorial caption treatment
+- floating toolbar with pill-shaped rounded actions
+
+### 3. Garden Path
+
+Use for:
+- onboarding flows
+- education apps
+- health and wellness
+- meditation and mindfulness
+- guided experiences
+
+Feel:
+- gentle
+- progressive
+- encouraging
+- like a guided walk through a garden
+
+Composition:
+- linear narrative flow
+- one step at a time, generous vertical rhythm
+- progress indicators that feel rewarding
+- illustrations or organic shapes as wayfinding
+
+Visual cues:
+- softer accent palette (muted terracotta, sage green, warm amber)
+- more rounded everything (pill buttons, oval badges, circular avatars)
+- gentle background gradients that shift with progress
+- decorative organic shapes (circles, blobs) in background — always subtle
+
+Signature ideas:
+- step indicator as garden path (dots connected by a curved line)
+- celebration moment with warm radial burst
+- floating encouragement card after milestones
+
+### 4. Reading Room
+
+Use for:
+- documentation platforms
+- knowledge bases
+- blog platforms
+- long-form content
+- journal apps
+
+Feel:
+- intellectual
+- measured
+- unhurried
+- like a quiet library with warm light
+
+Composition:
+- narrow, readable content column (max 680px)
+- generous margins
+- strong typographic hierarchy with minimal decoration
+- sidebar as table of contents, not feature list
+
+Visual cues:
+- serif dominance (headings AND body can be serif here)
+- book-like margins and line spacing
+- footnotes, pull quotes, and editorial details
+- minimal chrome — the content IS the interface
+
+Signature ideas:
+- pull quote with oversized serif and warm accent bar
+- chapter-style section breaks with ornamental divider
+- reading progress bar integrated into the top bar
+
+### 5. Warm Dashboard
+
+Use for:
+- analytics overview
+- admin panels
+- project management dashboards
+- finance overview
+- reporting tools
+
+Feel:
+- clear
+- trustworthy
+- comprehensive but not overwhelming
+- like a well-organized desk with everything in reach
+
+Composition:
+- stat cards as opening, but NOT four equal boxes
+- one hero metric or insight above the fold
+- tables and charts below, organized by priority
+- sidebar for navigation, content area for data
+
+Visual cues:
+- warm-toned chart colors (terracotta, amber, sage, slate — never neon)
+- card depth hierarchy: elevated stats > flat lists > subtle backgrounds
+- serif for stat numbers and section titles, sans for data labels
+- accent sparingly: one chart highlight color, not rainbow
+
+Signature ideas:
+- hero insight card with large serif number + trend context
+- warm-toned donut/bar chart with hand-picked palette
+- activity timeline with avatar bubbles and warm connecting line
+
+---
+
+## Signature Move Library
+
+Pick one and commit. Do not apply three weak gestures when one strong one would do.
+
+### Apps
+- greeting card with personalized context and warm illustration
+- soft left-accent border on priority items (3px rounded, warm coral)
+- inline milestone celebration with subtle confetti or warm burst
+
+### Dashboards
+- one hero insight with large serif number instead of four equal KPI cards
+- warm-toned chart palette that feels intentional, not default
+- activity feed with avatar timeline and connecting warm line
+
+### Landing Pages
+- split hero with product shot on warm gradient background
+- testimonial as editorial pull quote with serif and warm accent
+- feature sections with alternating illustration/text rhythm — never a grid of icons
+
+### Websites
+- editorial section headers with serif overline and warm divider
+- case-study cards with generous media and warm caption treatment
+- organic background shapes (circles, waves) that add warmth without distraction
+
+Rule:
+- your signature move must appear in at least 5 concrete places, or it is not a real signature
+
+---
+
+## Anti-Generic Tests
+
+Run these before presenting:
+
+### Swap Test
+
+If you swapped:
+- the serif headings for Inter or system sans
+- the warm colors for gray and blue
+- the rounded corners for sharp rectangles
+
+and the page still feels mostly the same, it is too generic.
+
+### Squint Test
+
+Blur your eyes:
+- can you still see hierarchy?
+- is there one dominant idea?
+- do the warm tones feel intentional or just tinted?
+
+Warmth should feel embedded, not painted on.
+
+### Signature Test
+
+Point to 5 exact places where the chosen signature appears.
+If you cannot name them, you do not have a signature.
+
+### Domain Test
+
+Hide the product name.
+Would the page still feel like it belongs to this specific product world?
+If not, you are decorating a template.
+
+### Coldness Test (unique to Warm Craft)
+
+Does any part of the page feel clinical, cold, or sterile?
+Check: gray cards without warm tint, sharp shadows, blue/purple accents, dense tables without breathing room.
+Fix: warm the tone, round the edges, add spacing.
+
+---
+
+## Variation Rules By Surface Type
+
+### Apps
+- Do not always start with a greeting card. Sometimes the primary content IS the greeting.
+- Sidebar should feel like furniture, not like a spreadsheet navigation.
+- Dense is never the goal — clarity through structure, not compression.
+
+### Dashboards
+- Avoid four equal KPI cards as the only opening move.
+- Prefer one insight story above the fold: a trend, a warning, a celebration.
+- Charts should use warm palette colors, never default library colors.
+
+### Landing Pages
+- Do not default to centered hero + three feature cards + testimonials + CTA.
+- Use editorial rhythm: alternating layouts, visual breaks, narrative pacing.
+- Illustrations should feel warm and hand-crafted, never cold and geometric.
+
+### Websites
+- Not every page needs to be light. Consider warm dark for dramatic sections.
+- Institutional does not mean boring — let typography, whitespace, and warmth carry the experience.
+- Let proof and narrative carry trust before using effects.
+
+---
+
+## Non-Negotiable Expression Rules
+
+1. One accent family, one expression mode, one signature move.
+2. The page must feel designed for a domain, not for a prompt category.
+3. Typography must carry personality before decoration does — serif headings are the anchor.
+4. Background warmth must feel natural, never tinted as an afterthought.
+5. If the design feels familiar, push the composition, not the gimmicks.
+6. Whitespace is not wasted space — it is the most important design element in this system.