@jaimevalasek/aioson 1.4.0 → 1.5.1

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

@@ -0,0 +1,339 @@
+# Art Direction - Cognitive Core 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 Cognitive Core from collapsing into the same dark dashboard 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 Cognitive Core DNA:
+- structured information zones
+- refined surfaces and subtle borders
+- disciplined accent usage
+- premium technical feel
+
+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 `cold`, `calm`, `surgical`, `elevated`, `urgent`, `editorial`, `trustworthy`, `tactical`.
+   Never use empty labels like `clean`, `modern`, or `beautiful`.
+
+4. **Domain vocabulary**
+   At least 5 concepts from the product's world.
+   Example for logistics: `dispatch`, `route`, `load`, `dock`, `throughput`.
+
+5. **Color world**
+   At least 5 colors or materials that belong to that product world.
+   Example: graphite glass, brushed steel, fog gray, oxidized teal, warning amber.
+
+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. Tactical Monolith
+
+Use for:
+- command centers
+- security tools
+- infra and monitoring
+- serious operational dashboards
+
+Feel:
+- cold
+- exact
+- high-trust
+- dense but controlled
+
+Composition:
+- dominant analysis panel
+- strong left or top navigation spine
+- grouped secondary rails
+- no playful overlap
+
+Visual cues:
+- graphite surfaces
+- restrained cyan or teal accent
+- tight vertical rhythm
+- mono labels as metadata rails
+
+Signature ideas:
+- inset command strip
+- segmented control bar
+- status tape above the main panel
+
+### 2. Quiet Graphite
+
+Use for:
+- premium SaaS apps
+- B2B platforms
+- productized internal tools
+
+Feel:
+- calm
+- precise
+- premium
+- composed
+
+Composition:
+- generous negative space inside a dark shell
+- fewer but larger cards
+- content grouped by narrative importance, not just equal grid repetition
+
+Visual cues:
+- soft border-first depth
+- low-contrast radial wash
+- bold headings with restrained body copy
+- minimal decorative noise
+
+Signature ideas:
+- oversized title rail
+- media-backed hero card
+- one sculpted panel breaking the grid
+
+### 3. Signal Editorial
+
+Use for:
+- landing pages
+- product websites
+- manifesto pages
+- strategy or brand-heavy experiences
+
+Feel:
+- intelligent
+- narrative
+- premium
+- atmospheric
+
+Composition:
+- asymmetric sections
+- split hero or offset headline
+- quote blocks, proof rails, editorial stacks
+- alternating calm and high-impact moments
+
+Visual cues:
+- stronger display typography
+- more whitespace
+- mono as flavor, not reading mode
+- refined textures, lines, or atmospheric backgrounds
+
+Signature ideas:
+- offset hero frame
+- vertical proof rail
+- manifesto block with oversized quote
+
+### 4. Luminous Light
+
+Use for:
+- client-facing apps
+- enterprise admin with light theme
+- trust-heavy workflows
+- finance, healthcare, legal, institutional
+
+Feel:
+- clear
+- trustworthy
+- measured
+- polished
+
+Composition:
+- strong content containers
+- crisp headers
+- one dominant task surface above the fold
+- compact but breathable forms and tables
+
+Visual cues:
+- off-white surfaces, not raw white overload
+- deep teal accent, never weak sky blue buttons
+- clear border hierarchy
+- low-noise status colors
+
+Signature ideas:
+- elevated action bar
+- proof card ribbon
+- sculpted table header band
+
+### 5. Industrial Flow
+
+Use for:
+- logistics
+- supply chain
+- manufacturing
+- devtools with utilitarian tone
+
+Feel:
+- practical
+- mechanical
+- legible
+- high-signal
+
+Composition:
+- rigid grid
+- strong lanes and divisions
+- labeled blocks with obvious purpose
+- timeline, feed, or throughput emphasis
+
+Visual cues:
+- colder neutrals
+- measured hazard accents
+- boxed callouts
+- minimal flourish, maximal clarity
+
+Signature ideas:
+- corner ticks
+- rail markers
+- striped progress treatment
+
+### 6. Gallery Intelligence
+
+Use for:
+- media-heavy apps
+- CRM/contact systems
+- AI agents, profiles, collections
+- catalog products with analytics
+
+Feel:
+- curated
+- intelligent
+- dimensional
+- premium
+
+Composition:
+- large hero card or profile surface
+- supporting detail rail
+- modular cards with strong hierarchy between thumbnail, title, metadata, and status
+
+Visual cues:
+- cleaner spacing around media
+- tighter metadata rows
+- one expressive showcase area per viewport
+
+Signature ideas:
+- profile marquee panel
+- inset media frame
+- layered details strip
+
+---
+
+## Signature Move Library
+
+Pick one and commit. Do not apply three weak gestures when one strong one would do.
+
+### Apps
+- segmented command bar with active underline and secondary metadata
+- sculpted workspace header with embedded actions
+- inset task rail that feels part of the shell, not pasted above content
+
+### Dashboards
+- one dominant hero metric surface instead of four equal KPI cards
+- trend arc or sparkline ribbon integrated into the main header
+- alert tape, timeline spine, or live activity lane
+
+### Landing Pages
+- offset split hero instead of centered everything
+- manifesto quote block with asymmetric CTA cluster
+- product theater frame with layered caption rails
+
+### Websites
+- editorial section header with overline, side note, and supporting proof
+- case-study strip with alternating image/text rhythm
+- atmospheric background treatment that supports the narrative without drowning the content
+
+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 typeface for a common SaaS font
+- the layout for a default sidebar + card grid
+- the hero for a centered headline + two buttons
+
+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?
+- are borders, glows, or accents screaming?
+
+Craft should whisper, not shout constantly.
+
+### 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.
+
+---
+
+## Variation Rules By Surface Type
+
+### Apps
+- Do not always start with a stat row.
+- Do not always use a fixed left sidebar if a topbar + workspace rail fits better.
+- Dense does not mean crowded; keep one task dominant.
+
+### Dashboards
+- Avoid four equal KPI cards as the only opening move.
+- Prefer one focal story above the fold: alert cluster, trend panel, hero metric, queue, or live map.
+- Tables should feel integrated into the system, not pasted from a CRUD starter.
+
+### Landing Pages
+- Do not default to centered hero + three feature cards + testimonials + CTA.
+- Use at least one composition break: split layout, offset media, vertical rail, or alternating section cadence.
+- Every section should have a different job, not the same card rhythm repeated four times.
+
+### Websites
+- Not every page needs dark mode.
+- Institutional does not mean bland; use typography, measure, editorial rhythm, and section contrast.
+- Let proof, narrative, and structure carry beauty 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.
+4. Background atmosphere must support content, never compete with it.
+5. If the design feels familiar, push the composition, not the gimmicks.

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

@@ -105,7 +105,7 @@ Entity header with avatar, name, role, badges, and stat cards.
 ```
 
 - Avatar: `96px`, `border-radius: var(--radius-lg)`, `border: 2px solid var(--border-subtle)`
-- Name: `--text-3xl`, `--weight-black`, `--tracking-tight`, `--text-heading`
+- Name: `--text-3xl`, `--weight-bold` by default, `--weight-black` only for a deliberately dramatic hero/profile treatment, `--tracking-tight`, `--text-heading`
 - Role: `color: var(--text-accent)`, `font-style: italic`, `--text-lg`
 - Tagline: mono, `--text-xs`, `--text-muted`, `--tracking-widest`, uppercase
 - ID: mono, `--text-xs`, muted, absolute positioned below avatar

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

@@ -11,6 +11,106 @@ These presets help choose a fitting operational composition instead of defaultin
 1. Start from the product's **main operational pressure**, not from a visual trope.
 2. Pick **one dominant preset** per screen.
 3. Mix small traits from another preset only when the primary composition is already clear.
+4. Choose one opening composition from the library below before placing a stat row.
+
+---
+
+## Opening Composition Library
+
+Do not let every dashboard begin with `4 KPI cards + tabs + equal grid`.
+
+Choose one primary opening move:
+
+### 1. Dominant Hero Surface
+
+Use when:
+- the screen has one main operational story
+- users need a fast read on what matters most
+
+Composition:
+- one large hero analysis panel
+- 2-3 supporting metrics beside or below
+- secondary cards deferred downward
+
+Best for:
+- control centers
+- analytics
+- AI orchestration
+
+### 2. Alert and Queue First
+
+Use when:
+- urgency beats summary
+- users act from exceptions, incidents, or pending work
+
+Composition:
+- alert cluster or priority queue above the fold
+- supporting health metrics nearby
+- context rail for recent events
+
+Best for:
+- ops
+- support
+- logistics
+- monitoring
+
+### 3. Trend First
+
+Use when:
+- change over time matters more than static totals
+- the main question is movement, not snapshot
+
+Composition:
+- chart or trend ribbon as the hero
+- compact stat strip
+- ranked list or narrative summary below
+
+Best for:
+- revenue
+- analytics
+- performance
+
+### 4. Profile or Entity First
+
+Use when:
+- one active entity anchors the workflow
+- the user is working inside a person, account, project, or agent
+
+Composition:
+- profile header or entity summary surface
+- focused stat cards
+- detail tabs and contextual rails
+
+Best for:
+- CRM
+- account management
+- AI agent panels
+
+### 5. Workspace First
+
+Use when:
+- the dashboard is really a working surface, not just a summary
+- users spend time editing, reviewing, or operating from this page
+
+Composition:
+- tool surface or main work pane dominates
+- navigation and status become secondary chrome
+- metrics move to support rails
+
+Best for:
+- admin tools
+- builder UIs
+- review flows
+
+---
+
+## Anti-Template Rules
+
+- Never open every dashboard with four equal stat cards unless the product truly lives and dies by four equal KPIs.
+- Never let the stat row be the most memorable part of the page.
+- If the layout could be mistaken for a generic admin starter after removing the colors, redesign the composition.
+- One strong focal block beats six medium-interest cards.
+- Use `references/art-direction.md` to choose a signature move before styling panels.
 
 ---
 

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

@@ -17,7 +17,7 @@ Default to **system fonts** first. Add Google Fonts only when the agent decides
 
 **Google Fonts (optional — use when building the Mentes Sintéticas aesthetic explicitly):**
 ```css
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;900&family=JetBrains+Mono:wght@400;500;600;700&display=swap');
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap');
 
 --font-display: 'Inter', system-ui, sans-serif;
 --font-body:    'Inter', system-ui, sans-serif;
@@ -108,6 +108,10 @@ Include this full block in every project.
   --transition-slow:  300ms ease;
   --transition-theme: background 240ms ease, color 240ms ease, border-color 240ms ease, box-shadow 240ms ease;
 
+  /* Shared interaction tokens */
+  --focus-ring-width: 2px;
+  --focus-ring-offset: 2px;
+
   /* Z-index */
   --z-base:     0;
   --z-elevated: 10;
@@ -150,6 +154,7 @@ Include this full block in every project.
   --accent-glow:   rgba(34, 211, 238, 0.12);
   --accent-subtle: rgba(34, 211, 238, 0.08);
   --accent-hover:  #06b6d4;
+  --accent-contrast: #07131a;
 
   /* Semantic */
   --semantic-green:      #16c784;
@@ -198,16 +203,17 @@ Include this full block in every project.
   --text-primary:   #334155;
   --text-secondary: #61748a;
   --text-muted:     #8b9aae;
-  --text-accent:    #0f8cc7;
+  --text-accent:    #0f766e;
   --text-inverse:   #f8fbff;
 
-  /* Accent — sky blue (legible on white) */
-  --accent:        #0ea5e9;
-  --accent-strong: #0284c7;
-  --accent-dim:    rgba(14, 165, 233, 0.10);
-  --accent-glow:   rgba(14, 165, 233, 0.08);
-  --accent-subtle: rgba(14, 165, 233, 0.05);
-  --accent-hover:  #0284c7;
+  /* Accent — deeper teal for AA-friendly buttons and links */
+  --accent:        #0f766e;
+  --accent-strong: #115e59;
+  --accent-dim:    rgba(15, 118, 110, 0.10);
+  --accent-glow:   rgba(15, 118, 110, 0.08);
+  --accent-subtle: rgba(15, 118, 110, 0.05);
+  --accent-hover:  #115e59;
+  --accent-contrast: #f8fbff;
 
   /* Semantic */
   --semantic-green:      #059669;
@@ -284,6 +290,18 @@ body { font-family: var(--font-body); }
 .shell[data-theme="dark"] { --bg-base: #0b0f15; font-family: var(--font-body); }
 ```
 
+---
+
+## Interaction Guardrails
+
+These rules exist to stop the most common quality failures: illegible hover states, washed-out light theme buttons, and decorative overload.
+
+1. Primary actions on accent backgrounds must use `var(--accent-contrast)`, not `var(--bg-base)`.
+2. Hover states may change brightness, but must preserve or improve text contrast.
+3. Focus styles must be visible on both themes. Minimum: `outline: var(--focus-ring-width) solid var(--accent)` with `outline-offset: var(--focus-ring-offset)`.
+4. If a control background becomes lighter on hover, its foreground must be re-evaluated. Do not assume the base text color still works.
+5. Favor one accent family and two neutral text tiers over adding extra decorative colors.
+
 **Unsafe (font breaks silently):**
 ```css
 /* WRONG */
@@ -344,6 +362,20 @@ line-height: var(--leading-relaxed);
 color: var(--text-primary);
 ```
 
+### Primary Action
+
+```css
+background: var(--accent);
+color: var(--accent-contrast);
+border: none;
+font-family: var(--font-body);
+font-size: var(--text-sm);
+font-weight: var(--weight-semibold);
+letter-spacing: var(--tracking-wide);
+```
+
+Use mono only for short command-like labels. Default buttons should stay in the body family for better readability.
+
 ### Numbers in tables and lists
 
 ```css
@@ -361,6 +393,7 @@ font-feature-settings: "tnum" 1;
 4. Above the fold: prefer 1 primary content block + 1 support block + 1 contextual rail — not a wall of equal cards.
 5. Mono labels are separators, not decoration. If everything is uppercase mono, nothing is important.
 6. In brownfield: fix cascade and token-scope errors before changing colors, layout, or density.
+7. Interactive controls must align on shared heights (`--control-sm`, `--control-md`, `--control-lg`) and shared text baselines.
 
 ---
 
@@ -488,3 +521,4 @@ Never keep secondary tools always visible — they crowd the primary content.
 6. Keep **one obvious focal block** per viewport.
 7. Fix token scope and cascade bugs before redesigning colors or layout.
 8. In admin/operational UI, apply the **Compact Density** scale — never carry consumer/marketing spacing into dense panels.
+9. Validate contrast and hover/focus parity before considering a screen finished.

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

@@ -108,6 +108,37 @@ CTA buttons: fadeInUp  450ms   500ms
 
 ---
 
+## Expression-Aware Motion
+
+Match motion to the expression mode chosen in `references/art-direction.md`.
+
+### Tactical Monolith
+- Keep motion short, directional, and low drama
+- Prefer panel reveals, status updates, and quiet count-up behavior
+- Avoid floaty motion, oversized parallax, or decorative loops
+
+### Quiet Graphite
+- Use soft fades, small elevation shifts, and measured reveal delays
+- Let motion reinforce polish, not spectacle
+
+### Signal Editorial
+- Use more narrative sequencing: headings, side notes, proof blocks, and media can enter in layered stages
+- Favor stagger and reveal rhythm over obvious bounce or glow pulses
+
+### Luminous Light
+- Keep motion crisp and clean
+- Favor focus, control feedback, and gentle surface lifts over cinematic effects
+
+### Industrial Flow
+- Motion should feel functional and linear
+- Sliding panels, queue shifts, progress fills, and status transitions work better than float or blur-heavy effects
+
+### Gallery Intelligence
+- Let media frames, profile blocks, and showcase surfaces reveal with slightly richer sequencing
+- Keep metadata motion subtle so the content remains primary
+
+---
+
 ## Hover Effects
 
 ### Card Hover
@@ -235,3 +266,12 @@ const TT = { transition: 'background 240ms ease, color 240ms ease, border-color
 | Modal/Detail | Light | scaleIn entrance, fadeIn backdrop |
 | Loading state | Ambient | Skeleton shimmer, pulse glow |
 | Admin CRUD | None/minimal | Only theme transition + hover states |
+
+---
+
+## Anti-Generic Motion Rules
+
+- Do not use the same stagger recipe on every page type.
+- Do not animate everything just because motion is available.
+- One memorable sequence beats constant moving surfaces.
+- If motion draws more attention than hierarchy or content, reduce it.

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

@@ -89,7 +89,7 @@ For viewing a single entity (person, product, contact, project).
   object-fit: cover;
 }
 .profile-name {
-  font-family: var(--font-display); font-weight: var(--weight-black);
+  font-family: var(--font-display); font-weight: var(--weight-bold);
   font-size: var(--text-3xl); color: var(--text-heading);
   letter-spacing: var(--tracking-tight); line-height: var(--leading-tight);
 }