@jaimevalasek/aioson 1.4.0 → 1.6.0

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

@@ -0,0 +1,210 @@
+---
+name: clean-saas-ui
+description: Clean SaaS UI is a design system for professional, neutral B2B interfaces that prioritize clarity, consistency, and efficiency. Use it when `design_skill: clean-saas-ui` is set in project.context.md OR when the user explicitly asks for "clean SaaS", "professional dashboard", "business app", "admin panel", "neutral UI", "no-frills", "enterprise", "CRM", "ERP", "internal tool", or similar. Ideal for B2B SaaS products, admin panels, CRM systems, project management tools, internal enterprise apps, and any product where reliability and efficiency matter more than visual flair. Supports apps, dashboards, and marketing sites — light by default with a polished dark variant. Do NOT use this skill unless explicitly selected.
+---
+
+# Clean SaaS UI
+
+Clean SaaS UI sits at the intersection of **professional neutrality** and **systematic precision** — a design system optimized for the humans who live inside B2B software for 8 hours a day. No personality for personality's sake. No decoration that costs attention. Just excellent, reliable, efficient UI.
+
+Inspiration: Stripe Dashboard, Linear app, GitHub, Notion (app), Figma (panels).
+
+**This is one visual system.** Never combine it with another design skill.
+
+## Package structure
+
+```text
+.aioson/skills/design/clean-saas-ui/
+  SKILL.md                      ← you are here (load this first)
+  references/
+    art-direction.md            ← intent, expression modes, signature moves, anti-generic tests
+    design-tokens.md            ← CSS variables light + dark, typography, spacing, radius, shadows
+    components.md               ← All reusable components (table, filter bar, sidebar, form groups, etc.)
+    patterns.md                 ← Page layouts: app shell, list, detail, form, dashboard, settings, onboarding
+    dashboards.md               ← Dashboard presets: SaaS metrics, CRM, PM, support, admin overview
+    websites.md                 ← Landing/marketing page patterns + anti-patterns
+    motion.md                   ← Animations: fast functional transitions, micro-interactions, reduced motion
+```
+
+## Activation rules
+
+- Apply this package **only** when `project.context.md` contains `design_skill: "clean-saas-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 default / dark optional)
+
+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. **Professional neutrality** — Cores neutras com um único accent blue (não teal, não terracotta — azul clássico de confiança). Zero personalidade excessiva. O design é invisível — o usuário foca no trabalho, não na UI. Parece que "sempre esteve ali".
+2. **Systematic consistency** — Cada componente segue um grid rígido. Spacing 8px base, strict. Heights de controle fixos. Nenhum componente inventado ad-hoc. Tudo vem do sistema. O resultado parece um kit comercial de alta qualidade (Stripe Dashboard, Linear app).
+3. **Data-friendly density** — Density média: mais compacto que warm-craft, menos que cognitive-core. Tables, forms e lists são cidadãos de primeira classe. O sistema é otimizado para mostrar dados de forma limpa com scan rápido.
+
+## Theme system
+
+```html
+<div data-theme="light">   <!-- or data-theme="dark" -->
+```
+
+- **Light (default)**: apps, dashboards, admin — a maioria dos SaaS B2B
+- **Dark**: optional, para preferência do usuário ou ambientes low-light
+- Toggle always available by default
+
+If the user does not specify: default to **light with a theme toggle** in the top bar.
+
+## Visual DNA
+
+### Colors — light theme (default)
+- Background void: `#F3F4F6` (gray-100)
+- Background base: `#F9FAFB` (gray-50)
+- Surface: `#FFFFFF`
+- Elevated: `#F3F4F6` (gray-100 — hover, nested)
+- Primary accent: `#2563EB` (blue-600 — professional blue)
+- Text heading: `#111827` (gray-900)
+- Text primary: `#374151` (gray-700)
+- Text secondary: `#6B7280` (gray-500)
+- Text muted: `#9CA3AF` (gray-400)
+
+### Colors — dark theme
+- Background void: `#111827` (gray-900)
+- Background base: `#1F2937` (gray-800)
+- Surface: `#374151` (gray-700)
+- Elevated: `#4B5563` (gray-600)
+- Primary accent: `#3B82F6` (blue-500 — brighter for dark bg)
+- Text heading: `#F9FAFB`
+- Text primary: `#E5E7EB`
+
+### Typography
+- Headings and body: `Inter`, system-ui, sans-serif — both. Differentiator is weight and tracking, not family.
+- Headings: weight 600–700, letter-spacing -0.02em
+- Body: weight 400, tracking normal
+- Mono (metadata only): `JetBrains Mono`, uppercase, 0.675rem — used sparingly in code, IDs, table row metadata
+
+### Layout structure (app)
+```
+┌──────────────────────────────────────────────────────────┐
+│  SIDEBAR (256px)  │  PAGE HEADER: title + actions         │
+│  Logo             ├──────────────────────────────────────┤
+│  Nav groups       │  FILTER BAR (when list/table page)   │
+│  Active: blue     ├──────────────────────────────────────┤
+│  left border 2px  │  CONTENT AREA                        │
+│                   │  (table / form sections / charts)    │
+│  Footer: user     │                                      │
+└───────────────────┴──────────────────────────────────────┘
+```
+
+### Signature details
+- Active sidebar item: `border-left: 2px solid var(--accent)` + `bg-elevated`
+- Active tab: `border-bottom: 2px solid var(--accent)` + accent text
+- Inputs: 36px height (control-md), 1px border, 6px radius
+- Card hover: shadow-sm → shadow-md, 150ms, no translateY lift
+- Separator: borders over shadows — clean and flat
+- Buttons: flat, no gradients, consistent 36px height
+- Badges: radius-full, height 20px, px-2, 6 semantic variants
+- Tables: alternating row bg optional, sticky header, inline actions on hover
+
+## 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 and anti-generic decisions.
+- Never combine this package with `interface-design`, `cognitive-core-ui`, `warm-craft-ui`, `bold-editorial-ui`, or any other design skill.
+- Reuse the project's component library if one exists — map Clean SaaS 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 manager reviewing team workload before assigning a new batch"
+- "account exec scanning their CRM pipeline for deals at risk"
+- "calm, efficient, trustworthy, invisible — the tool gets out of their way"
+
+## 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.
+
+## 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.
+- Keep one spacing rhythm per surface: 8px increments, aligned text edges, consistent control heights.
+- When a layout feels chaotic, reduce variant count first. Do not add decorative layers.
+- Hardcoded colors, arbitrary shadows, and one-off font choices are design-system failures.
+- Sameness is failure. If the result looks like a default Tailwind UI starter, iterate before presenting.
+- Every page must pass the Blue Test: does the accent blue feel "chosen" or "default"?
+- Every full page must pass the Template Test: if you remove the logo and change the accent, does it still look like your product?
+- Tables must never stack into card lists on mobile — they scroll horizontally.
+
+## Positioning vs other skills
+
+| Aspect | clean-saas-ui | warm-craft-ui | cognitive-core-ui |
+|--------|--------------|---------------|-------------------|
+| Accent | Blue (#2563EB) | Terracotta | Teal/Cyan |
+| Headings | Sans-serif (Inter) | Serif (Source Serif) | Sans-serif (Inter) |
+| Radius | Medium (8px cards) | Large (16px+ cards) | Small-Medium |
+| Density | Medium | Low | High |
+| Personality | Neutral/professional | Warm/human | Premium/tactical |
+| Default theme | Light | Light | Dark |
+| Best for | B2B SaaS, admin, CRM | B2C, productivity, health | Command centers, ops |
+
+## Delivery modes
+
+### Greenfield
+1. Choose page variant (list, detail, form, dashboard, settings, onboarding, landing)
+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 Clean SaaS 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/clean-saas-ui/references/art-direction.md

@@ -0,0 +1,319 @@
+# Art Direction — Clean SaaS UI
+
+Read this file for any page-level work where differentiation matters: apps, dashboards, landing pages, websites, and major flows.
+
+This file exists to stop Clean SaaS UI from collapsing into the same generic Tailwind admin starter every time.
+
+The system stays coherent, but the expression must change with the product, the user, and the dominant task.
+
+---
+
+## Core Rule
+
+**Same system, different expressions.**
+
+Keep the Clean SaaS DNA:
+- systematic component consistency
+- neutral professional blue accent
+- data-friendly medium density
+- light-first with controlled shadows and borders
+
+But do **not** keep the exact same composition, header, table layout, or sidebar structure from product to product.
+
+---
+
+## 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 words such as `efficient`, `trustworthy`, `methodical`, `calm`, `precise`, `grounded`, `authoritative`.
+   Never use empty labels like `clean`, `modern`, or `professional`.
+
+4. **Domain vocabulary**
+   At least 5 concepts from the product's world.
+   Example for CRM: `deal`, `pipeline`, `stage`, `account`, `close date`.
+
+5. **Color world**
+   At least 5 tones or materials that belong to that product world.
+   Example for finance: cool gray, document white, navy authority, amber caution, muted green approval.
+
+6. **Defaults to avoid**
+   Name 3 obvious UI choices that would make the result generic.
+
+7. **Signature move**
+   One memorable design detail that can appear in at least 5 places on the page.
+
+If you cannot produce 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. Structured Workspace
+
+Use for:
+- project management
+- task trackers
+- team collaboration tools
+- sprint boards
+
+Feel:
+- organized
+- reliable
+- efficient
+- predictable
+
+Composition:
+- sidebar navigation clara, content area com sections bem definidas
+- header actions consistentes no topo da página
+- breadcrumb trail sempre presente
+- collapsible sidebar com transição suave
+
+Visual cues:
+- borders sutis para separação de seções (não shadows)
+- badge chips para status
+- avatar groups para team
+- inline editable fields
+
+Signature ideas:
+- breadcrumb + page title sempre juntos, nunca separados
+- task row com hover reveal de ações inline
+- sidebar com grupos colapsáveis rotulados
+
+---
+
+### 2. Data Table Pro
+
+Use for:
+- CRM
+- ERP
+- analytics admin
+- inventory management
+- financial data
+
+Feel:
+- efficient
+- scannable
+- precise
+- trustworthy
+
+Composition:
+- table como elemento dominante da página
+- filter bar horizontal acima da table
+- bulk actions bar aparece ao selecionar linhas
+- column sorting e pagination clean abaixo
+
+Visual cues:
+- alternating row backgrounds sutis (gray-50 / white)
+- sticky header da tabela
+- inline action buttons aparecem no hover da row
+- badges de status dentro das células
+
+Signature ideas:
+- advanced filter builder como drawer lateral
+- column customization via dropdown
+- inline cell editing com confirmation bar
+
+---
+
+### 3. Form-Heavy Admin
+
+Use for:
+- settings
+- configuration panels
+- user management
+- compliance tools
+- onboarding setup
+
+Feel:
+- clear
+- methodical
+- helpful
+- professional
+
+Composition:
+- multi-section forms com vertical rhythm rígido
+- section dividers com header e description
+- inline validation em tempo real
+- sticky save bar no rodapé
+
+Visual cues:
+- label-above-input consistente em todo formulário
+- helper text em toda parte (text-xs, text-secondary)
+- section cards com header próprio
+- progress indicator se for multi-step
+
+Signature ideas:
+- auto-save indicator no header ("Saved 2 min ago")
+- section navigation sidebar à esquerda para forms longas
+- inline diff preview para mudanças críticas
+
+---
+
+### 4. Metric Hub
+
+Use for:
+- dashboards de métricas
+- reporting
+- KPI tracking
+- executive views
+- analytics
+
+Feel:
+- informative
+- clean
+- authoritative
+- at-a-glance
+
+Composition:
+- KPI cards → charts → tables (hierarquia vertical)
+- date range selector proeminente no header
+- export actions no header
+- drill-down disponível em cada seção
+
+Visual cues:
+- chart colors do sistema (blue-first, não cores default de library)
+- stat cards com trends (+ / - e cor semântica)
+- sparklines inline nos stat cards
+- chart backgrounds levemente separados do bg-base
+
+Signature ideas:
+- comparison toggle (vs previous period)
+- goal progress indicators em stat cards
+- drill-down table abaixo do chart
+
+---
+
+### 5. Onboarding Flow
+
+Use for:
+- setup wizards
+- account creation
+- integration config
+- first-run experiences
+
+Feel:
+- guided
+- clear
+- encouraging
+- professional
+
+Composition:
+- step progress bar no topo
+- content area centralizado, max-width 480–560px
+- clear actions no rodapé (back + continue)
+- completion feedback visual
+
+Visual cues:
+- numbered steps com estado visual (done / active / pending)
+- completion percentage ou progress bar
+- ilustrações simples geométricas (não hand-drawn)
+- contextual help tooltips
+
+Signature ideas:
+- checklist progress card como elemento central
+- integration logo grid para conexões
+- inline preview do que será criado
+
+---
+
+## Signature Move Library
+
+Pick one and commit. Do not apply three weak gestures when one strong one would do.
+
+### Apps & Dashboards
+- filter bar sempre visível acima de qualquer table — nunca escondida em modal
+- page header consistente: left (title + breadcrumb) + right (actions) — mesma estrutura em todas as páginas
+- sidebar active item: blue left border 2px + bg-elevated — sem glow, sem gradiente
+
+### Data Heavy Pages
+- sticky table header com sort indicators sempre visíveis
+- bulk action bar que desliza para cima quando rows são selecionadas
+- inline row actions que aparecem no hover (não em dropdown separado)
+
+### Forms & Settings
+- section cards com header azul (text accent) + description text-secondary
+- auto-save indicator discreto no corner superior direito
+- input helper text sempre presente, mesmo antes de erro
+
+### Marketing Pages
+- product screenshot com shadow-lg + radius-xl ligeiramente inclinado (2–3deg)
+- feature grid com ícone + título + descrição — clean, sem background nos cards
+- pricing table com coluna "most popular" com accent border e slight elevation
+
+---
+
+## Anti-Generic Tests
+
+Run these before presenting:
+
+### Template Test
+Remove the logo and change the accent color. Does the result still look like a specific product, or does it look like a Tailwind UI starter?
+
+If it looks like a starter: add one signature move.
+
+### Density Test
+Are there wasted empty zones OR areas that feel cramped?
+
+Clean SaaS = equilibrium — nem esparramo nem cramped. Medium density aplicado consistentemente.
+
+### Consistency Test
+- All inputs have the same height (36px control-md)?
+- All buttons have the same radius (6px)?
+- All tables have the same header style?
+- All page headers follow the same left/right pattern?
+
+Inconsistency is a system failure, not a style choice.
+
+### Blue Test (unique to this skill)
+Does the accent blue feel like "a chosen blue" or "default bootstrap blue"?
+
+The accent blue should have a personality — `#2563EB` (blue-600) is sharp and decisive, not soft and corporate. It should feel intentional, not default.
+
+### Domain Test
+Hide the product name. Does the page still feel like it was built for this specific product world? Or could it be any SaaS product?
+
+If generic: inject domain vocabulary into labels, section names, empty states, and helper text.
+
+---
+
+## Variation Rules By Surface Type
+
+### Apps
+- Do not always start with a stat row — some apps start with a table, a queue, or a task list.
+- Do not always use a fixed left sidebar if a top nav fits better (simpler products).
+- Active state must be unambiguous — blue left border is the primary indicator, not color alone.
+
+### Dashboards
+- Avoid four equal KPI cards as the only opening move.
+- Prefer one focal story above the fold: MRR trend, team workload, queue status, or alert count.
+- Charts must use the system's chart palette — never the library's default rainbow.
+
+### Forms & Settings
+- Every section must have a clear header — do not run form fields without grouping.
+- Validation must be inline — not only on submit.
+- Long forms must have a section navigation mechanism (sidebar links or step tabs).
+
+### Landing Pages
+- Do not default to centered hero + three feature cards + testimonials + CTA.
+- Use at least one composition break: offset screenshot, split layout, or alternating sections.
+- Every section should have a different job — not the same card rhythm repeated.
+
+---
+
+## Non-Negotiable Expression Rules
+
+1. One accent color (blue), one expression mode, one signature move per page.
+2. The page must feel designed for this specific domain, not for "a SaaS product."
+3. Typography carries the neutral character — weight and tracking, not family variety.
+4. Borders and backgrounds separate zones — shadows are minimal and purposeful.
+5. If the design feels familiar, push the composition before adding decoration.