soureeui 1.0.0

package/references/packages.md

@@ -0,0 +1,127 @@
+# Packages and Component Decisions
+
+The most common failure after bad visual design: reimplementing something the project already has, or installing something the project did not need.
+
+---
+
+## Decision ladder
+
+```
+Existing project component?        → reuse or extend it
+        ↓ no
+Existing installed dependency?     → adapt it
+        ↓ no
+Simple enough for the platform?    → native / CSS / framework capability
+        ↓ no
+Mature package fits?               → recommend, install only when justified
+        ↓ no
+                                    build a reusable custom component
+```
+
+Walk it top to bottom every time. Stop at the first yes.
+
+---
+
+## Before recommending any package
+
+- inspect the dependency manifest — is there already an equivalent?
+- framework and version compatibility
+- typing support when the project is typed
+- accessibility support — a component library that fails keyboard support is a liability, not a shortcut
+- maintenance signals: recent releases, open critical issues, active maintainers
+- runtime and bundle cost relative to the value
+- license compatibility
+- how much customization the design direction requires — a heavily-themed library often costs more than building
+- whether the feature is simple enough to not need it at all
+
+Never install because a package is popular. Never add a second library in a category the project already covers.
+
+## Proportionality
+
+| Need | Right answer |
+|---|---|
+| Hover transition, simple reveal | Native CSS |
+| Modal, dropdown, tooltip, tabs | Existing primitives library if present; otherwise a headless primitives package — these are accessibility-hard |
+| Sortable, filterable, paginated, virtualized table | Mature table library. Hand-rolling this is a multi-week trap |
+| Form with validation | Project's existing form approach; a form library only past real complexity |
+| One chart | Consider hand-built SVG or a light library |
+| A charting surface across the product | A real charting library |
+| Date picker | Library. Time zones, locales, and keyboard support are worse than they look |
+| Complex gesture, scroll, or layout animation | Established animation library |
+| Icon | The icon library (`imagery-and-icons.md`) |
+| Toast, command palette, drag and drop, rich text | Library — each is deceptively deep |
+
+## Recommendation format
+
+```
+Package:            <name>
+Use it for:         <specific capability>
+Why:                <technical or design reason>
+Why not custom:     <maintenance / accessibility / edge-case cost>
+Project fit:        <how it sits with the existing stack>
+Cost:               <bundle / runtime / API surface>
+```
+
+Present this before installing. If the project already covers the category, do not present it at all.
+
+---
+
+## Category reference
+
+Examples, not prescriptions. Choose by detected stack and existing conventions.
+
+| Category | Examples |
+|---|---|
+| UI primitives / headless | Radix UI, Headless UI, Ark, Base UI |
+| Component libraries | shadcn/ui, MUI, Mantine, Chakra, Ant Design |
+| Icons | Lucide, Heroicons, Phosphor, Tabler, Radix Icons |
+| Animation | Motion, GSAP, AutoAnimate |
+| Tables | TanStack Table |
+| Forms / validation | React Hook Form, Zod, Valibot |
+| Charts | Recharts, Nivo, ECharts, Chart.js, Visx |
+| Carousel | Embla, Swiper |
+| Drag and drop | dnd-kit |
+| Command palette | cmdk |
+| Notifications | Sonner, React Hot Toast |
+| Rich text | Tiptap, Lexical, ProseMirror |
+| Dates | date-fns, Day.js, Temporal polyfill, React Day Picker |
+
+Non-React stacks have their own equivalents; find the project's ecosystem standard rather than porting a React answer.
+
+---
+
+## Component architecture
+
+Create a component when it earns **reusability, maintainability, consistency, or readability**. Markup existing is not a reason.
+
+Prefer one component with variants over a family of adjectives:
+
+```
+Card variant="product" | "featured" | "compact"
+
+not:  ModernCard  BeautifulCard  PremiumCard  FancyCard
+```
+
+Organize by role, following whatever the project already does:
+
+```
+ui/          primitives: button, input, dialog
+layout/      shells, grids, containers
+navigation/  nav, breadcrumbs, tabs
+forms/       composed fields and form patterns
+feedback/    toast, empty state, error state, skeleton
+<domain>/    product-specific components
+sections/    page composition blocks
+```
+
+Avoid: a wrapper component that only adds a class, a component used once with ten props, an abstraction invented before the second use case exists.
+
+---
+
+## Reference-based design
+
+When the user supplies a reference site, screenshot, or design: extract principles, do not clone.
+
+Analyze composition, hierarchy, type system, spacing rhythm, color relationships, surface treatment, interaction patterns, information density. Then translate those principles into this product's content and constraints.
+
+Never copy another brand's identity, assets, or copy.

package/references/product-brief.md

@@ -0,0 +1,68 @@
+# Product Brief
+
+Design decisions come from product facts. Collect them cheaply, infer what is inferable, ask only what changes the work.
+
+---
+
+## What to establish
+
+| Question | Why it changes the design |
+|---|---|
+| What is the product? | Determines vocabulary, density, imagery, tone |
+| Who uses it? | A trader, a nurse, and a teenager need different densities and affordances |
+| What problem does it solve? | Sets what the first screen must communicate |
+| What is the primary user goal? | Sets the focal point |
+| What is the single most important action? | Sets the primary CTA and its placement |
+| What information matters most? | Sets hierarchy |
+| What is the expected journey? | Sets navigation and section order |
+| What is the brand personality? | Sets typography, color, motion character |
+| What sector? | Consumer, enterprise, developer, fintech, health, education, commerce, gov — each carries conventions users rely on |
+| What devices? | Mobile-first field use and desktop analyst use are different products |
+| Existing brand guidelines or assets? | Constraints beat invention |
+
+---
+
+## Infer, do not ask, when
+
+- the repository already answers it (existing screens, copy, tokens, logo, meta tags)
+- the request names the product type and the convention is strong ("an invoice app" implies dense tables, not hero imagery)
+- the answer would not change any decision being made now
+
+State the inference in one line and continue: *"Assuming a B2B ops audience on desktop, so density over decoration."*
+
+---
+
+## Ask when
+
+- two reasonable readings lead to materially different interfaces
+- brand constraints may exist and getting them wrong wastes the work
+- the primary action is genuinely ambiguous
+
+Keep it to a small number of targeted questions. Batch them into one message. Never run a questionnaire to look thorough.
+
+Good question shape — concrete, answerable, consequential:
+
+```
+Two things before I build:
+
+1. Primary action on this screen — start a trial, or book a demo?
+2. Existing brand colors and fonts, or do I choose?
+```
+
+Bad question shape: "What vibe are you going for?" · "Do you want it to be modern?" · asking for anything the repo already contains.
+
+---
+
+## Sector conventions worth respecting
+
+| Sector | Users expect |
+|---|---|
+| Enterprise / internal tools | Density, keyboard paths, predictable layout, table-first, no marketing gloss |
+| Developer tools | Monospace where it means something, code samples, dark mode parity, terse copy |
+| Fintech / banking | Numeric clarity, tabular figures, conservative color, unmistakable state, audit trails |
+| Healthcare | Legibility, error prevention, plain language, high contrast, no ambiguity |
+| Education | Progressive disclosure, clear progress, forgiving interaction |
+| Commerce | Product imagery leads, price and availability unmistakable, fast path to cart |
+| Consumer social | Speed, gesture, avatar and media density, thumb reach |
+
+Break a convention only deliberately, and say why.

package/references/responsive.md

@@ -0,0 +1,145 @@
+# Responsive
+
+Shrinking a desktop layout is not responsive design. Each breakpoint is a deliberate composition of the same content.
+
+---
+
+## Per-section worksheet
+
+Run this for every major section before building it. Write the answers down; they are design decisions, not implementation details.
+
+```
+What stacks?              multi-column → single column, and in what source order
+What reorders?            the visually-secondary column is often first on mobile
+What collapses?           nav → drawer, filters → sheet, table → cards, sidebar → tabs
+What scrolls sideways?    tables, chip rows, carousels — with a visible affordance
+What disappears?          genuinely secondary content only; never a core action
+What changes interaction? hover reveals need a tap or persistent equivalent
+What grows?               touch targets to ~44px, spacing between adjacent targets
+What shrinks?             display type scales down faster than body type
+What re-crops?            images whose subject would be cut out of the frame
+```
+
+A section that answers "nothing changes" at every breakpoint is either very simple or unexamined.
+
+---
+
+## Breakpoint strategy
+
+Design the **content's** breakpoints. Break where the layout stops working — where the measure gets too long, where columns get too narrow, where a table stops fitting. Not at device widths, which change every year.
+
+- follow the project's existing breakpoints. Consistency beats a better set
+- three to four named by intent, not by device, when starting fresh
+- **container queries over viewport queries** for components. A card in a sidebar and the same card in a main column need different layouts at the same viewport width. Query the container it sits in
+- fewer breakpoints held rigorously beats many applied loosely
+- mobile-first source order in most stacks: base styles are the small layout, each query adds
+
+## Fluid vs stepped
+
+| Property | Approach |
+|---|---|
+| Type scale | Fluid between a min and max, clamped at both ends. Never unbounded |
+| Spacing / section rhythm | Fluid or stepped, but tied to the scale; never arbitrary per breakpoint |
+| Layout structure | Stepped. Columns change at a decision point, not continuously |
+| Container width | Fluid with a max, plus a side gutter that never collapses to zero |
+
+Fluid type without a maximum produces absurd headlines on wide monitors. Fluid type without a minimum makes body text unreadable on small screens. Clamp both.
+
+---
+
+## Layout patterns
+
+| Pattern | What it does | Use when |
+|---|---|---|
+| **Stack** | Columns become rows in source order | Equal-weight content |
+| **Reflow** | Grid changes column count at each step | Card and tile collections |
+| **Reorder** | Source order differs from visual order at one size | A sidebar that must lead on mobile |
+| **Priority+** | Show what fits, move the rest into a "more" affordance | Toolbars, tab bars, nav |
+| **Off-canvas** | Secondary region slides in on demand | Navigation, filters, detail panels |
+| **Reveal** | Content hidden behind disclosure on small, visible on large | Dense metadata |
+| **Summary + detail** | List on small, list-plus-detail on large | Inbox, records, settings |
+| **Swap** | A genuinely different component per size | Table vs card list, menu vs drawer |
+
+Reordering visual position away from DOM order breaks the keyboard path. Reorder in the source where possible, and verify tab order afterward either way.
+
+---
+
+## Component-by-component
+
+### Navigation
+Horizontal bar → priority+ → drawer or bottom bar. Decide which, do not default to a hamburger. Keep the primary action visible outside the drawer. On mobile, a bottom bar reaches the thumb better than a top bar for frequent actions. Sticky headers cost vertical space and must earn it.
+
+### Tables
+Never a squashed table. Pick one:
+- horizontal scroll with the key column frozen and a visible scroll affordance
+- card-per-row on small screens, with the two or three fields that matter
+- summary column plus a detail view or sheet
+- column priority: hide low-value columns below a threshold, with a way to reveal
+
+Pair with: sticky header row, right-aligned numeric columns, tabular figures.
+
+### Forms
+One column on every size. Labels above fields. Group related fields. Correct input type and autocomplete per field so the right keyboard appears. Keep the submit action reachable when the on-screen keyboard is open. Inline validation that does not shift layout when a message appears.
+
+### Modals and overlays
+Dialog on desktop, full-screen or bottom sheet on small screens. Sheets need a drag or close affordance and must not trap scroll behind them.
+
+### Cards and grids
+Define the minimum readable card width and let the grid choose the column count from it, rather than hardcoding counts per breakpoint.
+
+### Images and media
+Art-direct the crop when the subject would be lost. Serve appropriate sizes. Always reserve the aspect ratio so nothing shifts on load. Video needs a poster and must not autoplay with sound.
+
+### Long-form text
+Constrain the measure to roughly 60 to 75 characters at every width. A full-width paragraph on a wide monitor is a responsive failure even though nothing overflows.
+
+---
+
+## Touch, pointer, and input
+
+- hover does not exist on touch. Anything revealed only on hover must have a tap equivalent or be persistent
+- query input capability rather than assuming from width: coarse pointer means bigger targets and no hover reliance
+- a device can have both. A laptop with a touchscreen must satisfy both paths
+- drag interactions need a keyboard and a non-drag alternative
+- avoid gestures as the only way to reach anything
+- respect safe areas on notched devices; keep interactive content out of the home-indicator strip
+- account for the on-screen keyboard: inputs must not end up hidden behind it
+
+---
+
+## Density
+
+Responsive is not only about width. The same product may need a comfortable density for occasional users and a compact density for people in it all day. If the product has a density switch, it is a token-level decision made at the same time as spacing, not a late retrofit.
+
+---
+
+## Verification
+
+| Width | Check |
+|---|---|
+| 320–360px | No overflow, no clipped text, targets reachable |
+| ~480px | Stack decisions read correctly |
+| ~768px | The awkward middle — most layouts break here |
+| ~1024px | Tablet landscape, sidebar decisions |
+| ~1440px+ | Measure is constrained, content is not stranded |
+
+Also verify: 200% browser zoom, 400% zoom for reflow compliance, landscape on a short viewport, a long-string worst case, and the largest realistic dataset.
+
+**No horizontal page scroll at any width, ever.** An overflowing element inside its own scroll container is fine; the page body scrolling sideways is a bug.
+
+---
+
+## Common failures
+
+| Symptom | Cause |
+|---|---|
+| Sideways page scroll on mobile | A fixed width, a negative margin, or an unconstrained image or table |
+| Text touching the screen edge | Gutter applied to an inner element instead of the container |
+| Tiny tap targets crowded together | Desktop spacing carried down unchanged |
+| Content hidden on mobile that users need | "Simplification" that removed a core action |
+| Mobile nav that hides the primary CTA | Everything swept into the drawer |
+| Layout shift as images load | Aspect ratio not reserved |
+| Unreadable line lengths on wide screens | No max width on text containers |
+| Keyboard covering the field being typed in | No scroll-into-view handling |
+
+Mobile should feel designed for mobile, not tolerated.

package/references/review-and-done.md

@@ -0,0 +1,98 @@
+# Review and Definition of Done
+
+Building is not finishing. Run this before reporting completion.
+
+---
+
+## Visual and UX review
+
+Look at the rendered result, at real widths, with real content.
+
+### Hierarchy
+- Is the most important content visible immediately, without scrolling?
+- Is the primary action obvious within seconds?
+- Does the screen have one clear focal point, not four competing ones?
+- Does the visual weight of each element match its actual importance?
+
+### Layout
+- Is everything aligned to the grid or to a deliberate exception?
+- Is spacing consistent and from the scale?
+- Is the composition balanced, and does it have a reading axis?
+- Do related items group and unrelated items separate?
+
+### Typography
+- Are headings legible and clearly ranked?
+- Is body text comfortable — size, line height, measure?
+- Is the hierarchy readable from a squint, with no text in focus?
+- Do long strings, long words, and translated text survive?
+
+### Color and surfaces
+- Are color roles used for their meaning?
+- Does contrast pass on text, icons, and focus rings?
+- Does dark mode hold, if the product has one?
+
+### Components
+- Is each component consistent with its siblings?
+- Are all states implemented: hover, focus-visible, active, disabled, loading, empty, error, success?
+- Does the empty state teach, and does the error state say what to do?
+
+### Responsive
+- Does mobile look designed, not compressed?
+- Any horizontal overflow at any width?
+- Are touch targets large enough and well separated?
+- Do tables, modals, and navigation have real mobile treatments?
+- Does it hold at 200% zoom?
+
+### Interaction
+- Does every action give immediate feedback?
+- Are destructive actions confirmed with consequence stated?
+- Is motion purposeful, and does reduced motion work?
+- Is there a loading treatment for anything that waits?
+
+### UX
+- Can a first-time user tell what to do?
+- Is navigation predictable and is there always a way back?
+- Are errors preventable, and recoverable when they happen?
+- Is cognitive load reasonable — is anything asking for more than it needs?
+
+### Visual identity
+- Does this feel specific to this product?
+- Does it pass the human-design test in `anti-ai-patterns.md`?
+- Are there at least two decisions no competitor would share?
+- Would a stranger recognize the product from a screenshot?
+
+### Engineering
+- Tokens used, no magic values?
+- Existing components reused, no duplicate abstraction added?
+- No unrelated refactoring, existing behavior preserved?
+- Dead code, unused styles, and unused dependencies removed?
+
+---
+
+## Definition of done
+
+Not done because it builds. Not done because it renders. Not done because the components work.
+
+Done when **all** hold:
+
+```
+[ ] UX is clear — primary action and next step are obvious
+[ ] Visual hierarchy is strong
+[ ] Design direction is applied consistently across every screen touched
+[ ] Components are coherent and states are implemented
+[ ] Responsive behavior is designed at every breakpoint
+[ ] Accessibility is verified, not assumed
+[ ] Interaction states exist: hover, focus, active, disabled, loading, empty, error, success
+[ ] Imagery is intentional, with placeholders and prompts where assets are missing
+[ ] Icons come from one library, used semantically
+[ ] Copy is real and product-specific
+[ ] Tokens are used throughout
+[ ] The interface does not look AI-generated
+[ ] The review above was run and its findings addressed
+```
+
+---
+
+## Reporting
+
+State what was built, what the review found, and what was left undone and why. If something was skipped — a state not implemented, a breakpoint not verified, an asset still a placeholder — say so plainly. Silence on a gap reads as completion.

package/references/workflow.md

@@ -0,0 +1,107 @@
+# Workflow
+
+The full loop, with the gate that must pass before each step ends.
+
+```
+Inspect → Understand → Direct → Plan → Systemize → Implement → Review → Refine
+```
+
+---
+
+## 1. Inspect
+
+Read the project before recommending anything. Determine:
+
+- framework / runtime / language / package manager
+- styling system (CSS, CSS modules, utility framework, CSS-in-JS, preprocessor, native platform styles)
+- existing design tokens or theme file
+- existing component library and existing in-project components
+- icon library
+- animation library
+- form, table, chart, editor libraries
+- routing and layout structure
+- naming, file, and folder conventions
+- accessibility and responsive conventions already in use
+- dependency manifest and relevant config files
+
+Cheap ways to find these: the dependency manifest, the theme/token file, one representative screen, one representative component, the global stylesheet.
+
+**Gate:** can name the stack, the styling system, and at least three components worth reusing — or has confirmed the project is empty.
+
+Never force a recommendation from a framework the project does not use. If the project already has a design system, extend it; do not replace it.
+
+---
+
+## 2. Understand
+
+See `product-brief.md`. Establish, by inference or by asking:
+
+product · audience · problem solved · primary user goal · primary action · most important information · expected journey · brand personality · sector · primary devices · existing brand assets or guidelines
+
+**Gate:** can state the primary user goal and the single most important action on the screen in one sentence each.
+
+---
+
+## 3. Direct
+
+See `design-directions.md`. Select a visual direction from product, audience, brand, content, UX needs, sector, and existing identity — never at random and never by trend popularity.
+
+Target: **one primary visual language plus at most one supporting technique.**
+
+If the requirements do not specify a style and more than one direction would genuinely work, present 2–3 named directions in three lines each and ask which to use. If the correct direction is obvious, state it and move on — do not manufacture a choice.
+
+**Gate:** the direction is named, and there is a product-specific reason for it.
+
+---
+
+## 4. Plan
+
+Write the design plan before implementation code. Template: `../templates/design-plan.md`. Covers direction, color, typography, layout, components, imagery, interaction states, accessibility.
+
+**Gate:** every color role, type level, and spacing step used later exists in the plan.
+
+---
+
+## 5. Systemize
+
+See `design-system.md`. Define or extend tokens before building many components. A system defined after ten components is a refactor, not a system.
+
+**Gate:** tokens exist for color, type scale, spacing, radius, elevation, motion, breakpoints, icon sizes.
+
+---
+
+## 6. Implement
+
+- build the smallest coherent change that fully delivers the request
+- follow the project's existing conventions over personal preference
+- component abstraction only where it earns reuse, maintainability, consistency, or readability
+- handle interaction states as they are built, not afterwards: hover, focus-visible, active, disabled, loading, empty, error, success
+- no unrelated refactoring
+- preserve existing behavior
+
+---
+
+## 7. Review
+
+See `review-and-done.md`. Look at the result, not just the code. Hierarchy, layout, typography, component consistency, responsive behavior, UX clarity, visual identity.
+
+**Gate:** the checklist has been run and findings are written down.
+
+---
+
+## 8. Refine
+
+Fix what the review found. Remove anything that survived only because it was already there: dead styles, unused effects, leftover dependencies, decoration without purpose.
+
+---
+
+## Scaling the process
+
+| Request | Process |
+|---|---|
+| Change a label, fix spacing on one element, swap an icon | Inspect, implement |
+| Add a component to an existing system | Inspect, implement to existing tokens, review |
+| New screen in an existing product | Full loop, plan can be short, direction inherited |
+| New product, redesign, "make it modern" | Full loop, explicit direction and plan |
+
+Ceremony on a small task is its own failure mode. So is skipping direction on a large one.

package/templates/design-plan.md

@@ -0,0 +1,124 @@
+# Design Plan Template
+
+Write this before implementation code on any non-trivial UI task. Keep it tight — a page, not a document. Delete rows that do not apply to the task.
+
+---
+
+## Product
+
+- **Product:** what it is, in one line
+- **Audience:** who uses it and in what context
+- **Primary user goal:**
+- **Primary action:** the one thing this screen must get people to do
+- **Most important information:**
+- **Devices:** where it is actually used
+- **Brand constraints:** existing identity, assets, guidelines — or "none, choosing"
+
+## Direction
+
+- **Primary visual language:**
+- **Supporting technique (at most one):**
+- **Why this fits:** two concrete product reasons
+- **Deliberately avoiding:** patterns that would weaken this specific design
+- **Originality anchors:** at least two decisions no competitor would share
+
+## Color
+
+| Role | Value | Notes |
+|---|---|---|
+| background | | |
+| surface | | |
+| surface-elevated | | |
+| text | | contrast vs background |
+| text-muted | | contrast vs background |
+| border | | |
+| primary | | |
+| primary-contrast | | |
+| secondary / accent | | |
+| success | | |
+| warning | | |
+| error | | |
+| info | | |
+
+Dark mode: yes / no. If yes, roles defined for both modes now.
+
+## Typography
+
+- **Display family:**
+- **Body family:**
+- **Mono family (if needed):**
+- **Weights in use:**
+- **Scale:** display / h1 / h2 / h3 / body-lg / body / body-sm / caption — with sizes, line heights, tracking
+- **Measure:** target characters per line for body text
+
+## Layout
+
+- **Container width / max content width:**
+- **Grid:** columns, gutters
+- **Spacing scale:**
+- **Section rhythm:** vertical space between major sections
+- **Desktop composition:**
+- **Tablet composition:**
+- **Mobile composition:** what stacks, reorders, collapses, scrolls, grows
+
+### Responsive per section
+
+| Section | Stacks | Reorders | Collapses to | Scrolls sideways | Hidden | Target size change |
+|---|---|---|---|---|---|---|
+| | | | | | | |
+
+- **Navigation on small screens:** drawer / bottom bar / priority+ — and where the primary action stays visible
+- **Tables on small screens:** scroll with frozen column / cards / summary plus detail
+- **Container queries needed for:** components that appear in more than one container width
+
+## Components
+
+| Component | Reused / extended / new | Variants | States needed |
+|---|---|---|---|
+| | | | |
+
+New dependencies, with justification (see `../references/packages.md`): none / list
+
+## Imagery
+
+| Slot | Purpose | Aspect ratio | Negative space | Asset status |
+|---|---|---|---|---|
+| | | | | real / placeholder + prompt |
+
+## Icons
+
+- **Library:** existing project library, or chosen one
+- **Sizes:**
+- **Where icons appear, and what they mean:**
+
+## Interaction
+
+- **Hover:**
+- **Focus-visible:** (never animated in)
+- **Active / pressed:**
+- **Loading:** inline / skeleton / determinate progress, per expected wait
+- **Empty:**
+- **Error:**
+- **Success:**
+
+### Motion
+
+| Moment | Job (feedback / continuity / hierarchy / progress / attention) | Duration | Easing | Origin |
+|---|---|---|---|---|
+| | | | | |
+
+- **Anything that animates without user action:**  (justify or cut)
+- **Reduced-motion alternative for each row above:**
+
+## Accessibility
+
+- **Contrast verified on:** text, muted text, icons, focus rings
+- **Keyboard path for the primary task:**
+- **Heading structure:**
+- **Labels and announcements:**
+- **Touch targets:**
+- **Reduced motion behavior:**
+
+## Copy
+
+Real, product-specific strings for headings, primary actions, empty states, and errors. Mark anything invented as invented.