@jaimevalasek/aioson 1.3.0 → 1.5.1

package/template/.aioson/skills/design/interface-design/references/handoff-and-quality.md

@@ -0,0 +1,71 @@
+# Handoff and Quality — Interface Design
+
+---
+
+## Quality checks (run before delivering)
+
+### Swap test
+Would swapping the typeface or layout make the design look like a different product?
+If yes — good. If no — the design has no identity.
+
+### Squint test
+Blur your eyes (or the screenshot). Does the visual hierarchy still read clearly?
+If not — the hierarchy is too weak.
+
+### Signature test
+Can you point to five specific decisions where your craft appears?
+If you cannot name five — you defaulted somewhere.
+
+### Token test
+Do your CSS variable names sound like they belong to THIS product?
+Generic: `--color-primary`. Specific: `--slot-available`, `--urgency-amber`.
+
+---
+
+## Self-critique before delivery
+
+Walk through each section before handing off:
+
+1. **Composition** — Does the layout have rhythm? Are proportions intentional? Is there one clear focal point?
+2. **Craft** — Is every spacing value on-grid? Does typography use weight + tracking + size (not size alone)? Do surfaces whisper hierarchy without thick borders or dramatic shadows?
+3. **Content** — Does the spec tell one coherent story? Could a real person at a real company act on this?
+4. **Structure** — Are there any hacks? Negative-margin workarounds? Arbitrary pixel values? Fix them.
+
+**Ask yourself: "If a design lead reviewed this, what would they call out?" Fix that thing. Then ask again.**
+
+---
+
+## Handoff to @dev
+
+A strong handoff includes:
+- Explicit visual direction and anti-goals
+- Design token block (fonts, colors, spacing, radius, depth strategy, motion posture)
+- Per-screen layout notes with component names mapped to real library components
+- Full state matrix (default / hover / focus / active / disabled / loading / empty / error / success)
+- Responsive rules (mobile breakpoints, collapse behavior)
+- Accessibility checklist items
+- Any signature visual moves with implementation notes
+- Anti-patterns to avoid
+
+The `ui-spec.md` must be concise enough to code from directly. Not a design document — a build contract.
+
+---
+
+## Update design memory
+
+When the work introduces or changes reusable design decisions, update `.interface-design/system.md` with:
+- Final direction and anti-goals
+- Token block
+- Component pattern notes
+- New exceptions or constraints
+
+This file is the continuity layer between screens, agents, and future sessions.
+
+---
+
+## Quality bar
+
+1. The result must not look generic.
+2. Repeated elements must share spacing, radius, and depth logic.
+3. Typography hierarchy must be legible without decorative tricks.
+4. The screen must communicate purpose before style.

package/template/.aioson/skills/design/interface-design/references/intent-and-domain.md

@@ -0,0 +1,74 @@
+# Intent and Domain — Interface Design
+
+> Read this before touching layout, tokens, or components.
+> Generic is the enemy. Every spacing value, typeface choice, and depth strategy is a decision. Own every one of them.
+
+---
+
+## The mandate
+
+If another AI, given the same prompt, would produce substantially the same output — you have failed.
+Defaults disguise themselves as infrastructure. Craft means owning every decision.
+
+---
+
+## Design memory and continuity
+
+If `.interface-design/system.md` exists, treat it as the visual source of truth:
+- Load it before changing direction, tokens, or component patterns.
+- Respect it unless the user explicitly wants a redesign.
+- Update it when you introduce a reusable pattern, token rule, or layout decision.
+
+If the file does not exist and the task covers more than one screen or component family, create it with:
+- Product context and UI intent
+- Chosen design direction and anti-goals
+- Token decisions (color, type, spacing, radius, depth, motion)
+- Core component patterns (navigation, card, table, form, modal, empty state)
+- Open constraints or decisions still pending
+
+One product should not look like it was designed from scratch on every screen.
+
+---
+
+## If the UI already exists
+
+When refining an existing product:
+- Identify the current visual direction before proposing a new one.
+- Diagnose token drift first: off-grid spacing, repeated hardcoded colors, mixed radii, mixed depth strategies, missing interactive states.
+- Improve consistency before re-theming.
+- Replace the direction only when the current system blocks the product intent or the user explicitly asked for a redesign.
+
+---
+
+## Phase 0 — Intent first (mandatory, cannot skip)
+
+Before touching layout or tokens, answer three questions with specificity:
+
+1. **Who is this human?** — Actual person, actual context.
+   Bad: "a user." Good: "a finance manager reviewing budget reports at 8am before a board meeting."
+2. **What must they accomplish?** — A specific verb, not a vague goal.
+   Bad: "manage their projects." Good: "approve or reject 15 expense requests before end of day."
+3. **What should this feel like?** — Concrete texture, not an adjective.
+   Bad: "clean and modern." Good: "a Bloomberg terminal that doesn't exhaust you."
+
+**If you cannot answer all three with specifics — stop. Ask. Do not guess. Do not default.**
+
+---
+
+## Phase 1 — Domain exploration (4 required outputs)
+
+Before proposing any visual direction, produce:
+
+1. **Domain concepts** — 5+ metaphors, patterns, or ideas from the product's world.
+   Example (clinic scheduling): appointment slots, patient flow, triage priority, clinical notes, white coat.
+
+2. **Color world** — 5+ colors that exist naturally in that domain.
+   Example (clinic): antiseptic white, calm blue (trust, clinical), soft green (go/available), amber (warning/urgent), warm gray (neutral).
+
+3. **Signature element** — One thing that could only belong to THIS product.
+   Example: a subtle "pulse" animation on available time slots, echoing a heartbeat.
+
+4. **Defaults to avoid** — 3 obvious, generic choices that must be replaced.
+   Example: blue primary button → calm teal; card shadows → border-only depth; Inter font → IBM Plex Sans (clinical precision).
+
+**The identity test:** Remove the product name. Could someone identify what this is for?

package/template/.aioson/skills/design/interface-design/references/tokens-and-depth.md

@@ -0,0 +1,173 @@
+# Tokens and Depth — Interface Design
+
+Lock these decisions before implementation. If you cannot state the checkpoint clearly, the system is not ready to build.
+
+---
+
+## Decision checkpoint (write this before any component)
+
+Before building any screen or component family, write a short checkpoint that locks:
+
+- **Depth strategy**
+- **Surface levels**
+- **Border recipe** (including alpha)
+- **Spacing base**
+- **Radius ladder**
+- **Control height**
+- **Typography anchor**
+- **Motion posture**
+
+Example (Sophistication & Trust):
+> Depth: borders-only • Surfaces: base / surface / elevated • Borders: rgba(15,23,42,0.08) • Spacing: 8px • Radius: 10/12 • Controls: 38px • Type: IBM Plex Sans 14/16/24 • Motion: 120ms ease-out
+
+Example (Premium Dark Platform):
+> Depth: borders-first • Surfaces: #0b1015 / #10161d / #151c24 • Borders: rgba(255,255,255,0.08) • Spacing: 8px • Radius: 12/14 • Controls: 40px • Type: Geist 14/16/28 • Motion: 140ms ease-out
+
+---
+
+## Token architecture (define all levels)
+
+### Color token families
+
+```
+foreground/primary     ← body text, labels, high-emphasis
+foreground/secondary   ← supporting text, placeholders
+foreground/muted       ← captions, disabled labels
+foreground/faint       ← decorative only, never critical
+
+background/base        ← page background
+background/surface     ← cards, panels
+background/elevated    ← modals, dropdowns (shadow system) or third surface level
+background/sunken      ← inputs, inset areas
+
+border/default         ← standard separator
+border/strong          ← focused inputs, active states
+border/faint           ← ultra-subtle dividers
+
+brand/primary          ← main CTA color
+brand/secondary        ← supporting brand accent
+
+semantic/success       ← green family
+semantic/warning       ← amber family
+semantic/danger        ← red family
+semantic/info          ← blue family
+```
+
+### Spacing — base × multiples only
+
+Never use arbitrary values (17px, 22px, 37px). Every value must be a multiple of your base.
+
+Common bases:
+- 4px base for dense/operational: 4, 8, 12, 16, 24, 32
+- 4px base for generous/consumer: 8, 12, 16, 24, 32, 48
+
+### Depth — pick ONE and commit
+
+| Strategy | When | Implementation |
+|---|---|---|
+| **Borders only** | Maximum density, zero visual noise | `border: 1px solid border/faint` |
+| **Subtle shadows** | Gentle, approachable feel | `box-shadow: 0 1px 3px rgba(0,0,0,0.08)` |
+| **Layered surfaces** | Modern minimal, dark platforms | Background elevation without shadows or borders |
+
+**Never mix depth strategies on the same surface.**
+
+### Radius ladder
+
+Define three values and use only them:
+- Sharp (small controls, tags, badges)
+- Medium (cards, inputs, buttons)
+- Large (panels, modals, sheets)
+
+### Typography anchor
+
+Define one font family and its full scale before touching components:
+
+```
+Page title    : largest size, 600-weight, tight tracking
+Section title : medium-large, 500-weight, normal tracking
+Body          : base size, 400-weight, line-height 1.5–1.6
+Helper / meta : small, 400-weight, muted color
+Data / mono   : monospace for numbers in tables, code, metrics
+```
+
+Size alone is never enough. Use weight + tracking + opacity to create layers.
+
+### Motion posture
+
+- Fast & utilitarian: 100–150ms ease-out
+- Comfortable & polished: 140–200ms ease-out
+- Expressive & refined: 200–300ms ease-out with spring for entrances
+
+Never animate layout properties (width, height, padding). Animate `transform` and `opacity` only.
+Always provide `prefers-reduced-motion: reduce` fallback.
+
+---
+
+## Operational density — admin / config / settings pages
+
+Settings pages, admin panels, config screens, and entity managers use a **compact scale** that overrides the default generous consumer spacing. Apply this whenever the user is operating a tool, not reading content.
+
+### Decision checkpoint for operational density
+
+> Depth: borders-first • Surfaces: 3-level (page / card / elevated) • Spacing base: 4px • Controls: 32px • Card padding: 16px outer / 12px nested • Type: xs-base range, text-base max for card headings • Radius: 22px outer / 18px nested / 14px deep
+
+### Card padding — 3-level scale
+
+| Level | Context | Padding | Radius |
+|---|---|---|---|
+| L1 | top-level section card | `16px` | `22px` |
+| L2 | card nested inside L1 | `12px` | `18px` |
+| L3 | inset block, disclosure body | `10px` | `14px` |
+
+Section gap: `12px` — not 16px or 24px.
+
+### Card headings
+
+- Section eyebrow: `0.68rem` uppercase mono, `tracking: 0.28em`
+- Section title: `text-base` (15–16px), `font-weight: 600` — **never `text-xl` or `text-2xl` inside a card**
+- Sub-info (path, ID): `font-mono text-[0.62rem]` single truncated line below title — no card for it
+- **No verbose description paragraphs** in admin cards — remove them or collapse to `<details>`
+
+### Form controls
+
+```
+Label  : 10–11px  margin-bottom: 2px
+Input  : px-3 py-2  (height ~32px)  text-xs  radius: 10–12px
+Select : same
+Button : px-3 py-2  text-xs  radius: 10–12px
+```
+
+The default 40px `min-height` rule in `## Forms` applies to consumer/public-facing forms. Admin/operational forms use 32px controls. Reduce only in authenticated tool contexts — never on public-facing login or onboarding.
+
+### List rows
+
+```
+Row     : py-2 (8px)  divide-y
+Gap     : gap-2.5
+Name    : text-xs font-medium  — not text-sm
+Model   : font-mono text-[0.65rem]  truncate
+Badges  : px-2 py-0.5 text-[0.6rem]  — not px-3 py-1
+Edit btn: px-2.5 py-1 text-[0.65rem]
+```
+
+### Entity grids (same-type objects: projects, agents, providers)
+
+Never stack same-type entities full-width. Use:
+```css
+grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+gap: 12px;
+/* Entity card: rounded-[18px] p-3 */
+```
+
+### Add/Edit → Modal, not accordion
+
+Inline form expansion (accordion, RevealPanel) inside entity cards creates visual clutter and unpredictable layout shifts. Use a modal:
+- `max-width: 448px`, centered, backdrop `bg-black/50 backdrop-blur-sm`
+- Single "+ Add" button outside the grid → opens modal
+- "Edit" button on each card → same modal pre-filled
+
+### Disclosure for secondary tools
+
+Sync assistants, cloud connect, advanced config, and other secondary actions go behind `<details>`:
+- Summary row: `flex items-center justify-between px-3 py-2.5` — label + status badge on left, action button on right
+- Never show secondary tools open by default in an already-dense panel

package/template/.aioson/skills/design/premium-command-center-ui/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: premium-command-center-ui
+description: Premium Command Center UI is a packaged visual system for tri-rail dashboards, dark operational shells, and premium command-center software. Use it only when `design_skill: premium-command-center-ui` is selected or the user explicitly chooses this package.
+---
+
+# Premium Command Center UI
+
+This is a specialized operational design skill.
+It is not the default for every dashboard.
+
+## Package structure
+
+```text
+.aioson/skills/design/premium-command-center-ui/
+  SKILL.md
+  references/
+    visual-system.md
+    patterns.md
+    operations.md
+    validation.md
+```
+
+## Activation rules
+
+- Apply this package only when `design_skill: premium-command-center-ui` is selected.
+- Do not load it in parallel with `cognitive-ui`, `interface-design`, or any other design skill.
+- Use it when the product genuinely needs a premium operational shell, not merely a dark dashboard.
+
+## Responsibility boundary
+
+This skill defines:
+- dark premium operational tone
+- tri-rail composition rules
+- density discipline
+- grouped operational cards and contextual rails
+- quality bar for command surfaces
+
+This skill does not decide framework, component library, or delivery format.
+
+## Loading guide
+
+| Task | Load |
+|---|---|
+| Any visual work | `references/visual-system.md` |
+| Dashboard shell and layout | `references/visual-system.md` + `references/patterns.md` |
+| Operational page hierarchy | `references/visual-system.md` + `references/patterns.md` + `references/operations.md` |
+| Final QA | add `references/validation.md` |
+
+## Positioning
+
+Use this package for:
+- command centers
+- control towers
+- orchestration software
+- activity-heavy internal operating surfaces
+- premium dark operational products
+
+Do not use it for:
+- landing pages
+- editorial or calm consumer products
+- simple CRUD screens that should stay neutral
+- generic SaaS dashboards without command-center pressure

package/template/.aioson/skills/design/premium-command-center-ui/references/operations.md

@@ -0,0 +1,74 @@
+# Operations — Premium Command Center UI
+
+---
+
+## Hierarchy rules
+
+1. **Show live pressure first.** Runtime operations appear above infrastructure or metadata.
+2. **Group cards by operational meaning**, not by raw data type.
+3. **Convert backend shapes into UI-native view models** when the user needs lanes, signals, grouped cards, or contextual summaries — not table rows.
+4. **Expose the next useful action** from every major block. Never leave the user without a clear path forward after reading a card.
+
+---
+
+## UI view model concept
+
+Do not render storage records directly as UI rows. Instead, aggregate backend data into objects shaped for operational reading.
+
+Examples from the AIOS Dashboard:
+- `GlobalTaskRecord` — combines task status, lane assignment, priority, and direct action into one card
+- `WorkflowRecord` — shows lifecycle stage, progress, blockers, and the one next step
+- `MemoryAssetRecord` — surfaces type, recency, source, and retrieval action
+
+Apply this in every new product: ask *"what does the user need to decide?"* and build the view model around that answer.
+
+---
+
+## How to preserve quality
+
+The quality bar is preserved when all of the following remain true:
+
+- Runtime or primary operations appear **above** infrastructure or metadata
+- Every screen has **one obvious focal block**
+- Cards are grouped by **operational meaning**, not just by data type
+- The shell behaves like a **product operating surface** — not a page of links
+- Semantic colors are **limited and consistent** — no rainbow status colors
+- Empty states are **styled and intentional** — never raw blank space
+- Search, navigation, and context **work together** instead of competing
+- Density is **compact but not cramped** — operational readability, not marketing whitespace
+
+---
+
+## When the system is working
+
+The result should feel like an operating surface:
+- Search and navigation reduce friction without competing with the workspace
+- Contextual rails support the current task without overloading the viewport
+- Live signals, queue state, history, and drill-downs coexist without collision
+- A user arriving at any screen can immediately read: *what is happening, what is next, what do I do*
+
+---
+
+## When to use this skill
+
+Apply `premium-command-center-ui` when:
+
+- The product is an operational dashboard or internal tool
+- The user asks for a premium, high-contrast, high-trust interface
+- The current UI feels washed out, generic, or too expanded
+- The app has multiple modules that need one shared shell and consistent hierarchy
+- The interface must surface live signals, queue state, history, and deep links
+
+---
+
+## When NOT to use this skill
+
+Do not apply this skill when:
+
+- The project is a landing page or campaign site
+- The product is intentionally minimal, calm, editorial, or consumer-soft
+- The existing brand system already conflicts with aurora-glass language
+- The screen is simple CRUD that should stay neutral and utilitarian
+- The domain demands conventional enterprise neutrality over expressiveness
+
+In those cases, borrow only the pieces that fit: density control, hierarchy discipline, grouped operational cards, or contextual rails.

package/template/.aioson/skills/design/premium-command-center-ui/references/patterns.md

@@ -0,0 +1,116 @@
+# Patterns — Premium Command Center UI
+
+---
+
+## Application flow
+
+Follow this sequence. Do not start from components. Start from operational pressure.
+
+### 1. Inspect the product before drawing anything
+
+Identify the real operational nouns and verbs:
+
+- What is the **live signal**? (running tasks, active events, real-time state)
+- What is the **queue**? (pending work, backlog, staged items)
+- What is the **grouped catalog**? (squads, agents, workflows, resources)
+- What deserves **persistent navigation**?
+- What belongs in **context**, not in the primary column?
+
+### 2. Translate raw data into UI-native objects
+
+Do not render tables straight from storage shape when the user actually needs lanes, signals, grouped cards, or contextual summaries.
+
+Convert backend records into view models. Examples from the AIOS Dashboard:
+- `GlobalTaskRecord` — aggregated task signal with lane/priority/status
+- `WorkflowRecord` — lifecycle-aware workflow with stage and next action
+- `MemoryAssetRecord` — knowledge item with type, source, and recency
+
+Apply the same principle in new projects. Ask: *what shape does the user need to think in?*
+
+### 3. Choose the shell intentionally
+
+Use the **tri-rail shell** when the product has:
+- 5+ first-class modules
+- Live or near-live context
+- A need for persistent navigation + persistent context panel
+- Enough desktop usage to justify a right rail
+
+Collapse progressively below the desktop breakpoint — do not build a separate mobile design system.
+
+**Tri-rail layout:**
+```
+┌────────────────────────────────────────────────────────┐
+│  TOP BAR: [Logo] [Search] [Workspace picker] [Actions] │
+├──────────┬─────────────────────────────────┬───────────┤
+│  LEFT    │                                 │  RIGHT    │
+│  NAV     │     CENTER WORKSPACE            │  ACTIVITY │
+│  RAIL    │     (primary column)            │  RAIL     │
+│  200px   │     one focal block per page    │  280px    │
+│  module  │     operational priority first  │  state    │
+│  icons   │                                 │  history  │
+│  + labels│                                 │  metrics  │
+└──────────┴─────────────────────────────────┴───────────┘
+```
+
+### 4. Choose the page archetype
+
+Pick the pattern that matches the page's job:
+
+| Archetype | Job | Focal block |
+|---|---|---|
+| **Command overview** | Surface live signals and current operational state | Priority queue or status summary |
+| **Queue / control tower** | Show pending work in processing order | Task lane or control grid |
+| **Grouped registry** | Browse and act on a categorized catalog | Group headers with inline actions |
+| **Workflow catalog** | Track multi-step flows from start to completion | Status-aware workflow cards |
+| **Knowledge explorer** | Find, filter, and inspect reference assets | Search bar + metadata panels |
+
+Use the UX playbook (operations.md) to decide which archetype fits each route.
+
+### 5. Apply the visual language without diluting it
+
+Preserve these moves together — removing any one degrades the whole:
+
+- Dark graphite or cool mist foundation
+- Aurora background fields on the page and shell — not on every card
+- Borders-first depth with one shadow family only
+- Three surface levels maximum
+- Compact spacing and short helper copy
+- Semantic badges and gradient fills tied to meaning, not decoration
+
+### 6. Build direct next actions into the UI
+
+Every major card must expose the next useful step:
+- Open the squad / agent / workflow
+- Inspect the task
+- View logs / history
+- Switch workspace
+- Drill into detail or source
+
+Premium feel comes from reduced friction, not only from color.
+
+---
+
+## Shell guardrails
+
+- Do not create equal-weight card walls for every section.
+- Every screen needs one obvious focal block.
+- Context and supporting data belong in side rails, not in the main narrative column.
+- Search and navigation must reduce friction — they cannot compete with the workspace.
+
+---
+
+## How to adapt this skill to new projects
+
+Adapt the system structurally, not literally.
+
+- Replace `squads` with the domain grouping that matters in the new product.
+- Replace `tasks` with the domain queue or active work item.
+- Replace `memories` with the project's knowledge layer, asset layer, or context layer.
+- Replace `activity rail` content with the three slices that matter most: current state, history, metrics.
+- Keep the same visual grammar and density discipline even when labels and data change.
+
+If the new project already has a design system:
+1. Port the hierarchy rules first
+2. Port the page archetypes second
+3. Port the shell behaviors third
+4. Port colors only if they do not violate brand or accessibility

package/template/.aioson/skills/design/premium-command-center-ui/references/validation.md

@@ -0,0 +1,47 @@
+# Validation — Premium Command Center UI
+
+Run this checklist before every handoff.
+
+---
+
+## Pre-ship checklist
+
+1. The page has **one dominant focal block** — not a grid of equal-weight cards.
+2. Density is **compact but not cramped** — operational readability, not marketing padding.
+3. Semantic colors are **limited and consistent** — no rainbow palette, no decorative gradients.
+4. The shell **supports the task** instead of decorating the viewport.
+5. There is a **direct next action** visible after reading each major block.
+6. The result does **not look like a generic dark dashboard with random gradients**.
+7. **Empty states are styled** — never raw blank space with no guidance.
+8. **Search, navigation, and context** work together without competing.
+
+---
+
+## Non-negotiable quality bar
+
+The following are absolute failures if present:
+
+- Flat, washed-out backgrounds without depth or surface levels
+- Equal-emphasis card grids for every section on every page
+- Giant padding values that make the product feel empty
+- Rainbow status colors without consistent semantic meaning
+- Shadow-heavy cards mixed with border-heavy cards on the same screen
+- No visible next step after the user reads a major card
+- Infrastructure-first hierarchy (metadata before live operations)
+- Top-level pages without a clear route back to the operating workflow
+
+If any of the above are present, the skill was not applied correctly.
+
+---
+
+## Expected output
+
+When this skill is applied to a new product, the deliverable must include:
+
+1. Explicit visual direction and density choice
+2. Shell structure and route hierarchy
+3. Page archetype selection per major screen
+4. Reusable component set with token assignments
+5. State handling: default / hover / active / empty / loading / error
+6. Responsive behavior notes (collapse strategy)
+7. Validation against this checklist before handoff