@polderlabs/bizar 6.2.5 → 6.3.0

package/bizar-dash/bizar-design/EXPLANATION.md

@@ -1,307 +0,0 @@
-# How To Use This Mockup To Build The Real UI
-
-This file explains how to turn the `bizar-design/` mockup package into the actual dashboard UI in `src/web/`.
-
-It is not a second design system. The design system already lives in:
-
-- `bizar-design/tokens.css`
-- `bizar-design/components.css`
-- `bizar-design/components.html`
-- `bizar-design/INSTRUCTIONS.md`
-
-This document explains how to **apply** that system during implementation.
-
-## What this package is for
-
-The mockup package does three jobs:
-
-1. It defines the **visual language**.
-2. It defines the **component contracts**.
-3. It defines the **screen structure and interaction behavior**.
-
-When building the real UI, do not treat these HTML files as disposable inspiration. Treat them as:
-
-- visual reference
-- naming reference
-- spacing and hierarchy reference
-- behavior reference
-- screen composition reference
-
-## What maps to what
-
-Use this mapping when implementing.
-
-### Foundations
-
-- `bizar-design/tokens.css`
-  - Maps to theme tokens in `src/web/styles/main.css`
-  - Source of truth for colors, spacing, radii, shadows, typography, and motion
-
-- `bizar-design/icons.svg`
-  - Maps to the icon set and sizing rules in the real app
-  - If using Lucide in React, match the same visual weight, size, and density
-
-- `bizar-design/components.css`
-  - Maps to reusable UI primitives in the real app
-  - Use it to derive component-level CSS classes or component APIs
-
-### Screen references
-
-- `bizar-design/desktop/overview.html`
-  - Maps to `src/web/views/Overview.tsx`
-
-- `bizar-design/desktop/agents.html`
-  - Maps to `src/web/views/Agents.tsx`
-
-- `bizar-design/desktop/memory.html`
-  - Maps to `src/web/views/Memory.tsx`
-
-- `bizar-design/desktop/settings.html`
-  - Maps to `src/web/views/Settings.tsx`
-
-- `bizar-design/desktop/metrics.html`
-  - Maps to `src/web/views/MiniMaxUsage.tsx`
-
-- `bizar-design/mobile/*.html`
-  - Map to `src/web/mobile/` views and components
-
-### System references
-
-- `bizar-design/canvas.html`
-  - Use this as the whole-product reference
-  - It shows how the system should feel when the pieces work together
-
-- `bizar-design/components.html`
-  - Use this as the detailed implementation catalog
-  - If you need a component or state, check here first
-
-## Correct implementation workflow
-
-Build the real UI in this order:
-
-1. **Read the target screen HTML**
-   - Start with the matching desktop or mobile screen file.
-   - Understand the layout, information priority, and module list.
-
-2. **Identify the reusable primitives**
-   - Find the corresponding pieces in `components.html`.
-   - Example: stat card, row list, sidebar item, settings block, info panel, timeline entry.
-
-3. **Implement primitives before screens**
-   - Do not build a whole screen by hardcoding layout-specific UI first.
-   - First create or update shared building blocks.
-
-4. **Bind to real data**
-   - Once the visual structure exists, connect it to the real view data in `src/web/views/` and `src/web/lib/types.ts`.
-
-5. **Apply interaction rules**
-   - Use `INSTRUCTIONS.md` and `components.html` for hover, focus, scroll, loading, empty, error, drag, and selection behavior.
-
-6. **Re-check against the mockup**
-   - Compare the implemented view to the target screen and the full canvas.
-
-## What not to do
-
-Avoid these mistakes:
-
-- Do not copy-paste mockup HTML directly into production and call it done.
-- Do not implement one-off CSS in a view when a shared primitive should exist.
-- Do not invent new spacing, border, or radius patterns per screen.
-- Do not shrink desktop layouts into mobile layouts.
-- Do not add decorative UI that is not in the system.
-- Do not let view code define its own interaction language separately from the design package.
-
-## How to read each file
-
-### `index.html`
-
-Use this as the package entry point.
-
-It tells you:
-
-- what references exist
-- where to start
-- which screen sets are available
-
-### `canvas.html`
-
-Use this to understand:
-
-- overall product posture
-- shell density
-- how different dashboard modules relate to each other
-- how the system should feel at a high level
-
-This is especially useful when a single view starts looking correct on its own but wrong in the larger system.
-
-### `components.html`
-
-Use this when:
-
-- you need to build a reusable component
-- you need a state variant
-- you need theming guidance
-- you need behavior guidance
-
-This should be the first stop before adding a new shared UI pattern.
-
-### `desktop/*.html`
-
-Use these as implementation contracts for desktop views.
-
-They define:
-
-- screen structure
-- layout regions
-- module ordering
-- density
-- navigation expectations
-
-### `mobile/*.html`
-
-Use these as implementation contracts for mobile views.
-
-They define:
-
-- what survives from desktop
-- what must stack or collapse
-- what gets simplified
-- how hierarchy changes on small screens
-
-## How to convert mockup patterns into real React components
-
-The safest pattern is:
-
-1. Find the repeated pattern in the mockup.
-2. Name it as a product primitive.
-3. Implement it as a reusable component.
-4. Move styling to shared styles.
-5. Reuse it across views.
-
-Examples:
-
-- Sidebar item
-  - mockup source: shell + components library
-  - real target: `Sidebar.tsx` plus shared sidebar styles
-
-- Metric card
-  - mockup source: overview + metrics screen
-  - real target: reusable stat/metric component
-
-- Activity row
-  - mockup source: overview timeline, approvals, background agents
-  - real target: shared row component with variant props
-
-- Settings block
-  - mockup source: settings screen + components library
-  - real target: reusable section wrapper used across settings subsections
-
-- Chat rail row / thread / info panel
-  - mockup source: chat composition section in `components.html`
-  - real target: shared chat module components under `src/web/components/chat/`
-
-## How to decide whether something belongs in shared code
-
-Put a pattern in shared code when at least one of these is true:
-
-- it appears on more than one screen
-- it has multiple states
-- it defines spacing or hierarchy others will copy
-- it is part of the shell or navigation
-- it is likely to need consistent behavior later
-
-If a piece is likely reusable, make it reusable early.
-
-## How to use the theming system
-
-Use the mockup tokens directly as the target vocabulary.
-
-That means:
-
-- `--bg`, `--bg-elev`, `--bg-elev-2`, `--bg-elev-3`
-- `--border`, `--border-strong`
-- `--text-strong`, `--text`, `--text-dim`
-- `--accent`
-- `--success`, `--warning`, `--error`, `--info`
-
-Do not create alternate naming systems in the real UI unless they map cleanly back to these tokens.
-
-## How to use behavior rules during implementation
-
-The behavior rules matter as much as visuals.
-
-Check these during development:
-
-### Scrolling
-
-- Does the correct region scroll?
-- Are headers or section rails preserved when needed?
-- Is there accidental horizontal overflow?
-
-### Hover
-
-- Does hover clarify affordance without causing visual noise?
-- Are important actions still visible without hover?
-
-### Focus
-
-- Can keyboard users understand where they are?
-- Does focus look like part of the system?
-
-### Click / selection
-
-- Is the primary action obvious?
-- Is selected state distinct from hover state?
-
-### Drag / reorder
-
-- Are drag targets visually clear?
-- Is there a visible drop state?
-
-### Loading / empty / error
-
-- Does the view preserve structure while state changes?
-- Does the user know what to do next?
-
-## Suggested implementation order for this repo
-
-If you are rebuilding the current dashboard from the package, the safest order is:
-
-1. Theme tokens in shared styles
-2. Topbar and expandable sidebar
-3. Shared primitives:
-   - buttons
-   - pills
-   - cards
-   - rows
-   - fields
-   - tables
-4. Overview
-5. Agents
-6. Memory
-7. Settings
-8. Metrics
-9. Mobile equivalents
-10. Polish pass across all screens together
-
-## Definition of “done” for an implemented screen
-
-A screen is only done when:
-
-- it matches the target mockup structurally
-- it uses shared primitives instead of ad hoc local ones
-- it uses the shared token language
-- it follows the interaction rules
-- it works with real data
-- it still looks consistent next to the other implemented screens
-
-## If you need to extend the mockup first
-
-If the real product needs a new pattern that the mockup package does not yet cover:
-
-1. Add or refine it in `bizar-design/components.html`
-2. Add any new shared rule to `bizar-design/INSTRUCTIONS.md`
-3. Add the shared primitive to `bizar-design/components.css`
-4. Then implement it in the real UI
-
-That keeps the mockup package as the actual reference instead of letting implementation drift away from it.

package/bizar-dash/bizar-design/INSTRUCTIONS.md

@@ -1,149 +0,0 @@
-# Bizar Design System
-
-This folder is the canonical visual and interaction reference for the dashboard redesign. It exists outside `src/web/` so the product UI can be implemented against stable contracts instead of drifting from ad hoc view work.
-
-## Package map
-
-- `tokens.css` — canonical OKLch theme tokens for dark and light modes.
-- `components.css` — modular shell, component, state, and layout primitives.
-- `icons.svg` — shared icon sprite for sidebar, tabs, and library examples.
-- `prototype.js` — theme toggle, segmented control demo behavior, and persistent expandable-sidebar behavior.
-- `index.html` — launcher for the full package.
-- `canvas.html` — full-system reference canvas.
-- `components.html` — extensive component, theming, and behavior library.
-- `desktop/*.html` — desktop screen contracts.
-- `mobile/*.html` — mobile screen contracts.
-
-## Primary rules
-
-1. Start from `tokens.css`. Do not invent new hardcoded colors, spacing, or radii in view files.
-2. Extend existing primitives in `components.css` before creating new ones.
-3. Add any new component pattern to `components.html` before shipping it into product code.
-4. Preserve the no-left-stripe rule. Active and alert states use fill, glow, label, or motion.
-5. Keep the package navigable. Launcher, canvas, library, desktop screens, and mobile screens must cross-link.
-
-## Modular architecture
-
-The system is organized in layers. Build in this order:
-
-1. **Tokens**
-   - Surface, text, accent, semantic, motion, spacing, radius, shadow, typography.
-2. **Shell**
-   - Topbar, expandable sidebar, tabs, search trigger, runtime pills.
-3. **Primitives**
-   - Buttons, fields, pills, badges, cards, rows, timelines, tables, bars, tabs.
-4. **States**
-   - Loading, empty, error, disabled, selected, streaming, paused, degraded.
-5. **Domain modules**
-   - Chat, agents, memory, settings, metrics, approvals, kanban, drawers, modals.
-
-Each component should be portable. If a component cannot be lifted from the library into React with minimal translation, it is too view-specific.
-
-## Theming inventory
-
-All theming items belong in the library. The package should always cover:
-
-- Surfaces: `--bg`, `--bg-elev`, `--bg-elev-2`, `--bg-elev-3`
-- Borders: `--border`, `--border-strong`
-- Text: `--text-strong`, `--text`, `--text-dim`
-- Accent: `--accent`, `--accent-2`, `--accent-3`, and derived soft/border/glow tokens
-- Semantics: `--success`, `--warning`, `--error`, `--info`
-- Type: sans, mono, display/title/body/meta sizes
-- Layout: spacing scale, radii, shadows
-- Motion: fast / base / slow durations and easing
-
-Any future theme extension must keep token names stable across dark and light modes.
-
-## Component coverage
-
-The library should maintain examples and usage rules for:
-
-- Topbar and expandable sidebar
-- Search triggers and project/runtime pills
-- Tabs and segmented controls
-- Buttons and destructive/success variants
-- Fields: text input, select, textarea
-- Pills, badges, dots, and avatars
-- Cards and nested surfaces
-- Metric cards and progress bars
-- Timelines, activity rows, and list rows
-- Tables and comparison layouts
-- Charts and sparkline shells
-- Chat rail, thread, composer, info panel
-- Memory rail, health hero, source blocks
-- Settings nav, settings groups, field clusters
-- Modals, drawers, inspectors, approval rows
-- Loading, empty, error, drag preview, drop zone
-
-## Interaction behavior rules
-
-These are part of the design system, not implementation details.
-
-### Scrolling
-
-- Independent regions scroll independently when they contain long content.
-- Preserve context with sticky headers or sticky section nav when content exceeds one screen.
-- Avoid horizontal page scroll on desktop; prefer internal scroll regions for tables and rails.
-- Mobile screens should stack modules vertically and scroll naturally; no tiny desktop canvases inside phones.
-
-### Hover
-
-- Hover indicates affordance, not surprise.
-- Surfaces lift one visual tier at most.
-- Border and text contrast may strengthen on hover.
-- Critical actions must not appear only on hover if they are required to operate the screen.
-
-### Focus
-
-- Focus uses the shared accent glow or border contract.
-- Keyboard focus must follow the same hierarchy as click targets.
-- Active and focused are distinct: focus is temporary, active is stateful.
-
-### Click
-
-- Primary click selects or opens.
-- Secondary actions live in explicit action buttons or menus.
-- Clickable rows need large targets and visible active states.
-- Do not overload one row with multiple hidden click targets.
-
-### Drag
-
-- Dragged items use accent-border outlines and elevated shadow states.
-- Drop zones use dashed outlines and clearer copy.
-- Reorder interactions must have keyboard or button alternatives when practical.
-- Drag state should never rely on color alone.
-
-### Loading
-
-- Prefer inline loading bars, pulse rows, or local placeholders over blocking page spinners.
-- Streaming states stay near the content being updated.
-- Preserve layout during loading to reduce jump.
-
-### Empty
-
-- Empty states explain what is missing and what the operator can do next.
-- Empty surfaces still need strong structure; they are not blank cards.
-
-### Error
-
-- Errors must preserve recovery context.
-- Always provide the next action: retry, inspect, reconnect, or review.
-- Use semantic error color sparingly and pair it with plain technical copy.
-
-### Responsive
-
-- Desktop is dense and multi-column.
-- Tablet collapses secondary columns before it reduces core content width.
-- Mobile rearranges modules into stacked flows with native-feeling spacing and clear hierarchy.
-
-## Implementation workflow
-
-1. Start from the closest existing primitive in `components.css`.
-2. If you need a new component, add the primitive first.
-3. Add or update the matching section in `components.html`.
-4. Apply the component in product code.
-5. Verify the new state still matches the shell, token, and behavior rules.
-
-## Intent
-
-This package is meant to be exhaustive enough that UI work in the dashboard can be implemented from it without guessing how things should look or behave. The screens show concrete usage, but the shared component and behavior contracts are the real deliverable.