@jaimevalasek/aioson 1.4.0 → 1.5.1

package/template/.aioson/skills/design/clean-saas-ui/references/websites.md

@@ -0,0 +1,295 @@
+# Websites — Clean SaaS UI
+
+Marketing and landing page patterns for B2B SaaS products. Clean, professional, and product-first.
+
+---
+
+## Principles
+
+- **Light by default** — Clean SaaS marketing pages are light. Dark sections exist for contrast moments, not as the base.
+- **Product-first** — The product screenshot or demo is the hero, not a generic illustration.
+- **Functional copy** — Headlines describe what the product does and for whom. No buzzwords without meaning.
+- **Contained radius** — Marketing cards max out at `radius-2xl` (16px). Never rounded beyond that.
+
+---
+
+## Hero Pattern A — Value Proposition Hero
+
+**Use for:** main product landing page, feature launch, primary CTA
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ [Logo]       Features   Pricing   Docs        [Sign in] [Start free →] │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  The CRM teams          [Product screenshot or          │
+│  actually use.           dashboard mockup — right half] │
+│                                                          │
+│  Manage deals, track     shadow-lg, radius-xl,          │
+│  contacts, and close     slight perspective tilt        │
+│  more revenue without    (2-3deg) optional              │
+│  the complexity.                                         │
+│                                                          │
+│  [Start free →]  [See demo]                             │
+│                                                          │
+│  ——————————————————————————————————————                 │
+│  Trusted by 1,200+ teams  [logo][logo][logo][logo]      │  ← social proof strip
+└─────────────────────────────────────────────────────────┘
+```
+
+**Specs:**
+- Layout: 50/50 or 55/45 text/visual split — left-aligned text
+- Headline: `text-4xl` (desktop) / `text-3xl` (mobile), `font-bold`, `tracking-tight`
+- Subtitle: `text-lg text-secondary max-w-md`
+- Primary CTA: `control-lg` button, accent
+- Secondary CTA: ghost button or text link
+- Screenshot: `shadow-lg rounded-xl` — use a real product screenshot, not a mockup illustration
+- Social proof: `grayscale` logos, `text-sm text-muted` label above
+- Background: `bg-base` or `bg-void` — never a gradient mesh
+
+---
+
+## Hero Pattern B — Centered Announcement Hero
+
+**Use for:** product launch, major feature announcement, simple landing pages
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                          │
+│              ┌──────────────────┐                        │
+│              │ ✨ New: AI Inbox  │  ← announcement badge │
+│              └──────────────────┘                        │
+│                                                          │
+│         The support tool that scales                     │
+│         with your team.                                  │
+│                                                          │
+│         Handle 10× more tickets without                  │
+│         adding headcount.                                │
+│                                                          │
+│         [Start free →]    [See how it works]             │
+│                                                          │
+│   ─────────────────────────────────────────────         │
+│   [Avatar][Avatar][Avatar] 1,200+ teams love it         │  ← avatar cluster + social proof
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Specs:**
+- All centered, `max-w-3xl` container
+- Announcement badge: `bg-accent-dim text-accent text-sm px-3 py-1 rounded-full font-medium`
+- Headline: `text-5xl font-bold tracking-tight` — up to 2 lines
+- Subtitle: `text-xl text-secondary max-w-xl`
+- Avatar cluster: 4 overlapping avatars + "X+ teams" text
+- Background: `bg-base` — optionally with subtle radial gradient to `bg-void` at bottom
+
+---
+
+## Hero Pattern C — Demo Hero
+
+**Use for:** products where interactivity is the differentiator
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                          │
+│   See it in action.                                      │
+│   No setup, no credit card.                              │
+│                                                          │
+│   ┌─────────────────────────────────────────────────┐   │
+│   │                                                 │   │
+│   │   [Interactive demo or video player]            │   │  ← full-width frame
+│   │                                                 │   │
+│   └─────────────────────────────────────────────────┘   │
+│                                                          │
+│        [Start free →]    [Book a demo]                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Specs:**
+- Dark section for the demo area — `bg-gray-900` or `bg-void dark` for contrast
+- Video/demo frame: `rounded-xl shadow-lg` with browser chrome optional
+- Headline above: `text-3xl font-bold text-heading`
+- CTAs below the demo, not above
+- Keep the section focused — no feature list competing with the demo
+
+---
+
+## Section Patterns
+
+### 1. Feature Grid
+
+**Use for:** feature overview, benefits section
+
+```
+┌──────────────────────────────────────────────────────────┐
+│         Everything you need to close more deals.          │
+│         subtitle text-secondary max-w-2xl centered        │
+├──────────────────────┬───────────────────┬───────────────┤
+│  [icon]              │  [icon]           │  [icon]       │
+│  Pipeline Views      │  Contact Intel    │  Team Inbox   │
+│  Visualize your…     │  Never miss a…    │  Collaborate… │
+├──────────────────────┼───────────────────┼───────────────┤
+│  [icon]              │  [icon]           │  [icon]       │
+│  Automation          │  Reporting        │  Integrations │
+└──────────────────────┴───────────────────┴───────────────┘
+```
+
+- Icon: 24–32px, `text-accent` or semantic color
+- Title: `text-base font-semibold text-heading`
+- Description: `text-sm text-secondary`
+- No card borders, no shadows — clean icon + text on page background
+- 3 columns desktop, 2 mobile, 1 below 480px
+
+---
+
+### 2. Feature Deep Dive
+
+**Use for:** flagship features, comparison with competitors, "how it works"
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  [Product screenshot — left]  The pipeline that moves.  │
+│                                No more stale deals.      │
+│                                                          │
+│                                See exactly where every  │
+│                                deal is and what's next. │
+│                                                          │
+│                                [→ Explore pipeline]      │
+├─────────────────────────────────────────────────────────┤
+│  Know your customer.          [Product screenshot — right]│
+│  Before the call.             ...                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+- Alternating left/right image+text
+- Screenshot: `rounded-xl shadow-md` — browser frame optional
+- Headline: `text-2xl font-bold` — benefit-focused, not feature name
+- Description: `text-base text-secondary max-w-sm`
+- Link: `text-accent font-medium` with `→` arrow
+
+---
+
+### 3. Testimonial Cards
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  ┌────────────────┐  ┌────────────────┐  ┌─────────────┐│
+│  │ "Cut our CRM   │  │ "Finally a     │  │ "The best   ││
+│  │ setup time by  │  │ sales tool our │  │ investment  ││
+│  │ 80%."          │  │ team loves."   │  │ we made."   ││
+│  │                │  │                │  │             ││
+│  │ [Avatar]       │  │ [Avatar]       │  │ [Avatar]    ││
+│  │ Jane S.        │  │ Mike T.        │  │ Sarah L.    ││
+│  │ VP Sales, Acme │  │ Founder, Beta  │  │ Ops, Gamma  ││
+│  └────────────────┘  └────────────────┘  └─────────────┘│
+└──────────────────────────────────────────────────────────┘
+```
+
+- Card: `bg-surface border border-default rounded-xl p-6 shadow-xs`
+- Quote: `text-base text-primary` — actual quote, not a paraphrase
+- Avatar: 40px, `radius-full`
+- Name: `text-sm font-semibold text-heading`
+- Role: `text-sm text-secondary`
+
+---
+
+### 4. Pricing Table
+
+```
+┌──────────────┬──────────────────┬──────────────┐
+│  Starter     │    Pro           │  Enterprise  │
+│              │  ┌ Most popular ┐│              │
+│  $29/mo      │  │   $79/mo     ││  Custom      │
+│              │  └──────────────┘│              │
+│  ✓ Feature   │  ✓ Feature       │  ✓ Feature   │
+│  ✓ Feature   │  ✓ Feature       │  ✓ Feature   │
+│  ✗ Feature   │  ✓ Feature       │  ✓ Feature   │
+│              │                  │              │
+│  [Get started]│ [Get started]   │  [Contact us]│
+└──────────────┴──────────────────┴──────────────┘
+```
+
+- Container: `grid grid-cols-3 gap-4`
+- Card: `bg-surface border border-default rounded-xl p-6`
+- Featured card: `border-accent border-2 shadow-md` — slight elevation
+- "Most popular" badge: `bg-accent text-white text-xs font-medium px-3 py-1 rounded-full`
+- Price: `text-3xl font-bold text-heading`
+- Feature list: `text-sm text-primary`, `✓` in `text-semantic-success`, `✗` in `text-muted`
+
+---
+
+### 5. Integration Logos
+
+```
+Works with your existing stack.
+
+[Salesforce]  [HubSpot]  [Slack]  [Zapier]  [Gmail]  [+40 more]
+```
+
+- Logos: grayscale, `opacity-60 hover:opacity-100 transition-opacity`
+- Grid: `flex flex-wrap gap-8 justify-center items-center`
+- Section title: `text-sm font-medium text-muted text-center mb-6`
+
+---
+
+### 6. CTA Banner
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                          │
+│       Start closing more deals today.                    │
+│       Free for 14 days. No credit card required.         │
+│                                                          │
+│                  [Start free →]                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+- Background: `bg-accent-dim` or `bg-elevated` — never full accent background
+- Headline: `text-2xl font-bold text-heading text-center`
+- Subtitle: `text-base text-secondary text-center`
+- CTA: primary button centered, `control-lg`
+- Padding: `py-16 px-6`
+
+---
+
+## Navigation (Marketing)
+
+```
+[Logo]       Features   Pricing   Customers   Docs      [Sign in]  [Start free →]
+```
+
+- Height: `64px`, `bg-surface/90 backdrop-blur sticky top-0 border-b border-default`
+- Logo: left-aligned
+- Nav links: `text-sm text-secondary hover:text-primary font-medium`
+- CTA: primary button `control-md`, right-aligned
+- Mobile: hamburger menu, full-screen overlay
+
+---
+
+## Footer
+
+```
+[Logo]                     Product      Company      Resources
+Tagline                    Features     About        Blog
+                           Pricing      Careers      Docs
+                           Changelog    Contact      Status
+
+─────────────────────────────────────────────────────────
+© 2026 ProductName. All rights reserved.     [Privacy] [Terms]
+```
+
+- `bg-surface border-t border-default`
+- Logo + tagline: left column
+- Link columns: `text-sm text-secondary hover:text-primary`
+- Bottom bar: `text-xs text-muted`
+
+---
+
+## Anti-patterns
+
+1. **Gradient mesh backgrounds** — not this skill; cognitive-core can use atmospheric effects
+2. **Hand-drawn illustrations** — that is warm-craft; use geometric SVG or product screenshots
+3. **Oversized dramatic typography** — that is bold-editorial; clean SaaS headlines are bold but not theatrical
+4. **Dark marketing pages as the default** — clean SaaS = light by default; dark sections for contrast moments only
+5. **Cards with radius > 16px** — contained radius, moderate feel
+6. **More than 2 font weights in a section** — clean, not editorial
+7. **Testimonials without real names and companies** — generic "happy customer" kills trust

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

@@ -15,6 +15,7 @@ The Cognitive Core system sits at the intersection of **military-grade data dash
 .aioson/skills/design/cognitive-core-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 dark + light, typography, token scope guardrails
     components.md               ← All reusable components (nav, stat card, badges, table, modal, DNA panel, etc.)
     patterns.md                 ← Page layouts: dashboard shell, detail/profile, settings, auth, list-detail
@@ -53,15 +54,15 @@ Always load only what the current task needs:
 |---|---|
 | Any UI work | `references/design-tokens.md` |
 | Reusable components | `references/design-tokens.md` + `references/components.md` |
-| Dashboard or admin panel | `references/design-tokens.md` + `references/components.md` + `references/patterns.md` + `references/dashboards.md` |
-| Detail / profile page | `references/design-tokens.md` + `references/components.md` + `references/patterns.md` |
-| Landing page or website | `references/design-tokens.md` + `references/components.md` + `references/websites.md` |
+| Dashboard or admin panel | `references/art-direction.md` + `references/design-tokens.md` + `references/components.md` + `references/patterns.md` + `references/dashboards.md` |
+| Detail / profile 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 six reference files |
+| Full UI build | all seven reference files |
 
 ## Visual signature — three pillars
 
-1. **Command-center authority** — Dense information when the product is operational. Monospaced uppercase labels on every section. Large numeric stat readouts. Everything feels like a mission control panel.
+1. **Command-center authority** — Dense information when the product is operational. Monospaced labels are used as metadata rails, not as the default reading style. Large numeric stat readouts. Everything feels like a mission control panel.
 2. **Premium refinement** — Three depth levels minimum (void → base → surface → elevated). Subtle borders (`rgba(255,255,255,0.06)` in dark). Teal/cyan as the only accent — used for active states, borders, glow effects. Never harsh contrasts.
 3. **Structured rhythm** — Tab navigation, sidebar trees, card grids, section headers with icons. Information is organized into labeled zones. One focal block per viewport.
 
@@ -99,9 +100,9 @@ If the user does not specify: default to **dark with a theme toggle** in the top
 - Text primary: `#334155`
 
 ### Typography
-- Headings: `Inter`, `weight-black (900)`, `letter-spacing: -0.02em`
+- Headings: `Inter`, usually `weight-bold (700)` or `weight-black (800)` only for hero/page title emphasis, `letter-spacing: -0.02em`
 - Body: `Inter`, `weight-normal (400)`, `line-height: 1.6`
-- Labels (most distinctive): `JetBrains Mono`, `weight-semibold`, `uppercase`, `letter-spacing: 0.15em`, `font-size: 0.675rem`
+- Labels (supporting only): `JetBrains Mono`, `weight-semibold`, `uppercase`, `letter-spacing: 0.12em`, `font-size: 0.675rem`
 - Stats: `Inter`, `weight-bold (700)`, `font-size: 2.75rem`
 
 ### Layout structure (dashboards)
@@ -123,7 +124,7 @@ If the user does not specify: default to **dark with a theme toggle** in the top
 ```
 
 ### Signature details
-- Monospace uppercase labels on every section (never skip this)
+- Monospace uppercase labels on major sections, stats, IDs, and metadata rails only
 - Badge chips with teal/cyan glow in dark mode
 - Progress bars with colored semantic fills (green/red/amber/purple)
 - Featured quote blocks: italic large text + mono attribution
@@ -135,12 +136,56 @@ If the user does not specify: default to **dark with a theme toggle** in the top
 ## 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 move, and anti-generic decisions.
 - Resolve the page variant before composing: dashboard uses dense operational rhythm; website/landing page uses more whitespace, hero typography, and narrative hierarchy.
 - Never combine this package with `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 Cognitive Core 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 data"
+- "clean and modern"
+
+Good answers:
+- "operations lead checking what needs intervention in under 30 seconds"
+- "sales manager comparing pipeline risk before a weekly meeting"
+- "calm, cold, exact, premium, slightly tactical"
+
+## Workflow discipline
+
+Extracted from stronger design-system practice, this skill must behave like a controlled system, not a moodboard:
+
+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 a lighter hover state if it reduces text contrast.
+- Never put near-white text on a bright accent in light theme. Use a darker accent or a darker foreground token.
+- Do not use mono for navigation groups, paragraphs, or long button copy.
+- Do not use `weight-black` as the default heading weight across the entire app.
+- Keep one spacing rhythm per surface: 4px/8px increments, aligned text edges, consistent control heights.
+- When a layout feels chaotic, reduce variant count first. Do not add more decorative layers.
+- Hardcoded colors, arbitrary shadows, and one-off font choices are design-system failures, not creative flourishes.
+- Sameness is failure. If the result could be mistaken for a default AI dashboard or centered SaaS hero, 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, stat-row, or card-grid composition across unrelated products without a domain reason.
+
 ## Delivery modes
 
 ### Greenfield
@@ -154,4 +199,5 @@ If the user does not specify: default to **dark with a theme toggle** in the top
 1. Audit existing UI before rewriting
 2. Map Cognitive Core tokens onto the existing component library
 3. Fix token scope issues (font/color variables must be on the correct container)
-4. Prefer targeted upgrades over full rewrites unless the user asks for a redesign
+4. Consolidate duplicate variants before introducing new ones
+5. Prefer targeted upgrades over full rewrites unless the user asks for a redesign