Add evidence-led Brand OS guidance

CHANGELOG.md

@@ -0,0 +1,75 @@
+# Wugweb Kits Design System — CHANGELOG
+
+All notable changes to the Kits design system will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] — 2026-07-26
+
+### Added
+- 4-layer token system (Core → Alias → Semantic → Component) in `src/styles/globals.css`
+- W3C DTCG-compliant token JSON files in `src/tokens/` (global.json, alias.json, semantic.json, component.json)
+- Style Dictionary build pipeline (`npm run tokens:build`, `npm run ds:tokens:build`)
+- Token validation scripts (`npm run validate:tokens`)
+- Design system documentation hub at `design-system/`
+- Source-of-truth docs in `design-system/docs/`
+- Component-per-folder wrappers under `src/components/ui/<Component>/index.ts`
+- Canonical bridge at `src/components/ui/index.ts`
+- Token normalization: removed space-based token keys, replaced with kebab-case
+
+### Changed
+- Migrated from raw hex/px values to token-based styling in UI components
+- Normalized all component tokens to reference semantic layer
+- Rebuilt `src/components/ui` with Radix-based primitives (accordion, alert, alert-dialog, etc.)
+
+### Pending
+- Full parity migration: 61 doc pages still import via `src/components/ui/legacy-adapters.ts`
+- Missing grouped components: AccordionGroup, AvatarGroup, AreaChart, BarChart, ButtonGroup, etc.
+- Missing custom components: Banner, CTABanner, ChatBubble, Clipboard, DeviceMockup, etc.
+- Screenshot-diff visual regression tooling (future work)
+
+## [1.0.2] — 2026-07-26
+
+### Changed
+- Removed dead `src/imports/` directory containing auto-generated Figma exports and unused SVG modules
+- Updated doc pages to fix TypeScript prop mismatches (`Patterns.tsx`, `AvatarDoc.tsx`, `TopicTileDoc.tsx`)
+- Replaced broken `ImageWithFallback` imports/usages with standard `<img>` elements
+- Fixed broken doc anchors in `TopicTileDoc.tsx` to use absolute doc paths
+- Replaced placeholder `href="#"` examples with plausible paths in `Patterns.tsx`
+
+## [1.0.1] — 2026-07-26
+
+### Added
+- Added token-based UI components: `banner`, `spinner`, `tag`, `kbd`, `logo`, `jumbotron`, `empty-state`, `list-group`, `indicator`, `timeline`, `grid`, `chat-bubble`, `side-menu`, `footer-links`, `cta-banner`, `search-input`, `number-input`, `device-mockup`, `button-group`, `accordion-group`, `avatar-group`
+- Added chart wrappers: `area-chart`, `bar-chart`, `line-chart`, `pie-chart`, `radar-chart`, `radial-chart`
+- Added Kits design system `CHANGELOG.md`
+
+### Changed
+- Updated `src/components/ui/index.ts` to export new components
+- Updated `src/components/ui/legacy-adapters.ts` to re-export from new token-based implementations
+- Added `Chart` export alias in `src/components/ui/chart.tsx`
+
+## [1.0.0] — 2026-07-21
+
+### Added
+- Initial component library with 50+ UI components
+- Base components: Button, Input, Card, Badge, Dialog, Dropdown, Tabs, etc.
+- Chart components: AreaChart, BarChart, LineChart, PieChart, RadarChart, RadialChart
+- Form components: Checkbox, RadioGroup, Switch, Slider, Select, DatePicker, etc.
+- Navigation: Header, Footer, SideMenu, MegaMenu, Breadcrumb, Pagination
+- Data display: Table, DataTable, ListGroup, Timeline, Avatar
+- Feedback: Toast, Spinner, Skeleton, Progress, Rating
+- Layout: Grid, Divider, Jumbotron
+- Utilities: Clipboard, SearchInput, Kbd, Tag, Chip, Logo
+- Block templates: Hero, Features, Pricing, Testimonials, CTA, Forms
+- Documentation site with component examples
+- Figma integration and token mapping docs
+
+### Infrastructure
+- Vite + React + TypeScript setup
+- Tailwind CSS v4 with custom @theme bridge
+- Sonner toast integration
+- Framer Motion animations
+- Supabase authentication framework
+- Recharts for data visualization

Wugweb_Brand_OS_Foundation/02_VISUAL_SYSTEM/04_COLOR_ROLES.md

@@ -7,3 +7,19 @@ Black provides authority and framing; white or warm off-white provides clarity;
 Use two to four accent colours per artwork. Keep people and most photography monochrome so colour belongs to the brand system. Avoid unapproved purple, green, orange, neon, rainbow palettes, and gradients.
 
 Limit each artwork to 2–4 accents plus neutral tones.
+
+## Token status
+
+The role system is approved. Exact hex tokens are **not yet canonical in this repository**. A supplied historical Wugweb design-system source visibly contains a primary pink plus named secondary blue, green, yellow, orange, purple, red, and turquoise swatches. This confirms that the brand has an extended campaign palette; it does not by itself establish the current production token set.
+
+Until verified tokens are added, use only colours drawn from an approved Wugweb reference and record the source in `05_REFERENCE_LIBRARY/14_EVIDENCE_LOG.md`.
+
+## Usage matrix
+
+| Mode | Typical palette behaviour |
+| --- | --- |
+| Editorial thought leadership | Off-white/black base plus 2–3 accents. |
+| Campaign collage | Black base or off-white base plus 3–4 approved accents. |
+| Product proof | Neutral product UI plus one or two structural brand accents. |
+| Systems/architecture | Neutral base, one anchor colour, restrained structural blue/cyan. |
+| Typographic collateral | High contrast; one headline colour field may dominate. |

Wugweb_Brand_OS_Foundation/02_VISUAL_SYSTEM/06_COLLAGE_SYSTEM.md

@@ -7,3 +7,9 @@ Assemble rather than illustrate: a warm/light or intentional dark background, on
 Elements must interact—holding, searching, selecting, assembling, navigating, or placing. Use clean cut-outs and natural overlap. Avoid torn-paper effects, heavy grain, random stickers, and image-generator clutter.
 
 Combine cut-out photography, geometry and restrained UI elements.
+
+## Evidence-aware scope
+
+Campaign references show that Wugweb can support a richer collage: editorial type panels, physical cards, device crops, multiple colour fields, and occasional print-like texture. This is a controlled campaign mode, not permission for arbitrary layering.
+
+Use the test: **does each layer clarify the same visual sentence?** If not, remove it. Dense connectors, dot fields, and grid marks are reserved for a systems/architecture concept.

Wugweb_Brand_OS_Foundation/02_VISUAL_SYSTEM/21_VISUAL_MODES.md

@@ -0,0 +1,33 @@
+# Visual Modes
+
+## Purpose
+
+Wugweb consistency comes from shared visual DNA, not one repeated layout. Select one mode before briefing or prompting an asset. Do not blend modes casually.
+
+## 1. Editorial thought leadership
+
+Use for blog heroes, article thumbnails, and strategic ideas. Build one visual sentence around a dominant object or geometry anchor, generous space, and minimal or no embedded explanatory text. A person or hand is optional.
+
+## 2. Campaign collage
+
+Use for social campaigns, service collateral, posters, and branded announcements. It may use bolder type panels, broader approved colour combinations, device crops, photography, and controlled overlap. It must still retain one hierarchy and one central metaphor.
+
+## 3. Product proof
+
+Use when the point is a real product experience. A single credible mobile, browser, map, recommendation, settings, or product module can act as evidence. Never fill the canvas with fake analytics widgets.
+
+## 4. Systems and architecture
+
+Use only when the subject is a process, information architecture, route, or relationship. Controlled maps, structured cards, linework, dots, grids, and connectors are allowed only because they are the metaphor—not as a generic AI effect.
+
+## 5. Typographic presentation
+
+Use for campaign posters, section dividers, presentation covers, and editorial social assets. Typography can be the hero visual; short copy is allowed when it functions as graphic form, not explanatory body text.
+
+## Selection questions
+
+1. Is the claim a strategic idea, a campaign message, a product interaction, a system, or a typographic statement?
+2. What one piece of evidence makes the claim tangible?
+3. Which mode makes that evidence most legible at the delivery format?
+
+See `08_ARTWORK_FORMULAS/FORMAT_DECISION_MATRIX.md` before creating the asset.

Wugweb_Brand_OS_Foundation/03_MARKETING_SYSTEM/16_AI_NATIVE_MARKETING_ROLES.md

@@ -0,0 +1,16 @@
+# AI-Native Marketing Roles
+
+## Purpose
+
+This is the canonical visual brief for the four-role article series. The series shares Wugweb colour roles, rounded geometry, editorial hierarchy, and credible product/physical evidence. The role metaphor must change from image to image.
+
+| Role | Core idea | Hero vocabulary | UI allowance | Avoid |
+| --- | --- | --- | --- | --- |
+| Agent Whisperer | Make a brand legible to intelligent agents. | Metadata cards, taxonomy labels, structured knowledge, folders, index systems. | One believable knowledge/search module if needed. | Robots, AI faces, chat bubbles as decoration. |
+| Full-funnel Navigator | Coordinate an adaptive ecosystem. | Routes, modular blocks, directional paths, priorities, movable systems. | One orchestration proof only. | Dashboard walls, equal-weight pathways. |
+| Hyperpersonalization Architect | Build trusted one-to-one experiences. | Mobile device, recommendations, preference chips, adaptive product modules. | One real mobile/product experience is appropriate. | CRM-like profile-card clutter. |
+| Customer Wayfinder | Turn scattered signals into meaning. | Map, compass, routes, markers, photos, curated fragments. | Usually none; a route/map module is enough. | Generic analytics charts or GPS-dashboard treatment. |
+
+## Series rule
+
+Keep the shared DNA, vary the metaphor. Do not repeat the same person-circle-card layout or the same hero object across the four assets.

Wugweb_Brand_OS_Foundation/05_REFERENCE_LIBRARY/00_INDEX.md

@@ -5,3 +5,16 @@
 References are evidence, not instructions to copy. Record source, date, ownership/rights, repeated observation, confidence, and the pattern or decision affected. The current Brand OS decision log wins conflicts between historical and current work.
 
 Master index for all evidence sources and analyses.
+
+## Current inventory
+
+- `16_PROJECT_SOURCE_INVENTORY.md` — project-local visual source audit and known evidence gaps.
+- `14_EVIDENCE_LOG.md` — evidence logging format.
+- `15_REFERENCE_CHECKLIST.md` — threshold before a reference becomes a reusable rule.
+
+## Evidence hierarchy
+
+1. Owned Wugweb source files and approved Figma tokens.
+2. Current public Wugweb website and portfolio work.
+3. Historical Wugweb collateral.
+4. External inspiration, used only for principle-level comparison.

Wugweb_Brand_OS_Foundation/05_REFERENCE_LIBRARY/16_PROJECT_SOURCE_INVENTORY.md

@@ -0,0 +1,21 @@
+# Project Source Inventory
+
+## Scope
+
+This inventory records the nine visual source files available in the Wugweb project mirror on 2026-07-26. They are reference evidence, not automatically approved production templates.
+
+| Source file | Observable evidence | Use in Brand OS |
+| --- | --- | --- |
+| `998aad18-e135-4444-97fc-5656aef4bf95(1).png` | Magenta anchor, yellow directional path, cyan block, monochrome hand/stairs, dots and dense connector system. | Evidence for the conditional systems/architecture mode; not the default collage density. |
+| `unnamed (7)(3).webp` | Wugweb design-system collateral; visible primary pink and extended named secondary palette; Inter typography. | Evidence for palette expansion and typography provenance; verify tokens in owned source before canonising. |
+| `unnamed(6).webp` | Digital Strategy collateral with oversized yellow circle, image/browser crop, blue speech bubble, black type panel. | Campaign collage and product-proof evidence. |
+| `unnamed (1)(5).webp` | Message Architecture collateral with high-contrast poster-like typography, rounded black title panel, bright shapes. | Typographic presentation mode. |
+| `unnamed (6)(11).webp` | Social Media Marketing collateral with device crops, portraits, bold colour fields. | Product/device proof in campaign mode. |
+| `unnamed (4)(7).webp` | Voice + Tone collateral with circular image masks and large type panel. | Editorial typography and controlled circular cropping. |
+| `unnamed (8)(4).webp` | Creative Direction collateral with framed art and a magenta anchor. | Curated reference/portfolio collage. |
+| `unnamed (3)(4).webp` | User Research collateral with large persona cards and yellow anchor. | Information-card mode when cards are real content, not fake UI filler. |
+| `unnamed (2)(3).webp` | Brand Strategy collateral with hands, puzzle object, yellow circle, black title panel. | Tangible-object metaphor and purposeful hand interaction. |
+
+## Missing evidence
+
+The project mirror currently contains no Master Theme PDF, source Figma file, finished four-role artwork, approved token file, or asset-rights record. Add them to `10_ASSETS/References/` or link them in `14_EVIDENCE_LOG.md` before elevating observations to permanent rules.

Wugweb_Brand_OS_Foundation/08_ARTWORK_FORMULAS/FORMAT_DECISION_MATRIX.md

@@ -0,0 +1,13 @@
+# Format Decision Matrix
+
+| Format | Default mode | Embedded text | UI allowance | Priority |
+| --- | --- | --- | --- | --- |
+| Article thumbnail / blog hero | Editorial thought leadership | None; headline sits outside the image. | None or one proof module. | One metaphor readable at small size. |
+| LinkedIn static post | Campaign collage or typographic presentation | Short statement can be graphic form. | One credible module. | Stop-scroll recognition. |
+| Carousel / presentation | Typographic presentation or systems/architecture | Allowed; type carries hierarchy. | Use only when the slide proves an interaction. | Sequential clarity. |
+| Service page / website section | Product proof or campaign collage | Interface/body copy belongs in page layout, not the illustration. | One credible product proof. | Product/service relevance. |
+| Case study cover | Editorial or product proof | Minimal title treatment. | One representative product frame. | Recognition and narrative cue. |
+
+## Rule
+
+“No text inside artwork” is not a universal Wugweb rule. It applies to no-text thumbnail and hero briefs. Format decides whether typography is excluded, minimal, or central.

Wugweb_Brand_OS_Foundation/09_VALIDATION/06_SOURCE_AND_RIGHTS.md

@@ -0,0 +1,13 @@
+# Source and Rights Validation
+
+## Before approval
+
+- Record the source of every photograph, UI screenshot, logo, external reference, and model-generated asset.
+- Confirm permission or licence status for external imagery and fonts.
+- Do not use a client product screen, customer data, or identifiable person without approval.
+- Use external studios such as COLLINS, Porto Rocha, Pentagram, or Instrument only as principle-level inspiration. Do not copy their specific composition, typography, imagery, or campaign assets.
+- Add alt text and check sufficient text contrast whenever text is part of the final delivery.
+
+## Evidence label
+
+Every reusable reference should be marked one of: `owned`, `licensed`, `public-reference-only`, `generated`, or `unknown — do not reuse`.

Wugweb_Brand_OS_Foundation/10_ASSETS/References/README.md

@@ -4,4 +4,14 @@
 
 Store owned, licensed, or link-only evidence here using `YYYY-MM-source-topic.ext`. Every asset needs source URL, rights status, date, and the observation it supports. A reference without notes is inspiration, not usable evidence.
 
-Describe the purpose and organization of this asset collection.
+## Current known evidence
+
+The project-source audit is recorded in `../../05_REFERENCE_LIBRARY/16_PROJECT_SOURCE_INVENTORY.md`. Before adding an asset, record where it came from, its date, rights status, and the specific observation it supports.
+
+## Required missing assets
+
+- Approved Figma/token export.
+- Wugweb Master Theme PDF or page exports.
+- Approved/rejected examples from the four AI-native marketing role series.
+- Screenshots or exported frames from the current website and public case studies.
+- Original/licensed source photography used in campaign collateral.

Wugweb_Brand_OS_Foundation/CHANGELOG.md

@@ -9,3 +9,10 @@
 
 ## v0.1
 - Initialized repository.
+# 2026-07-26 — evidence and mode audit
+
+- Added visual-mode selection to prevent false conflicts between editorial, campaign, product, systems, and typographic work.
+- Added project-source inventory for nine available visual references.
+- Clarified provisional colour-token status and extended-palette evidence.
+- Added canonical AI-native marketing role briefs, format decision matrix, and source/rights validation.
+- Added evidence-driven P0/P1 backlog.

Wugweb_Brand_OS_Foundation/CURRENT_CONTEXT.md

@@ -11,3 +11,11 @@ Build an evidence-driven Brand OS.
 - Objects over dashboards
 - One dominant geometric anchor
 - Conceptual metaphors
+
+## Audit update — 2026-07-26
+
+The current project-source audit confirms that Wugweb has both a restrained editorial mode and a richer campaign-collage mode. Neither cancels the other. Choose the mode from the content objective and format before selecting components.
+
+The exact brand token source has not yet been attached to this repository. The palette names and role rules are operational guidance; any hex value must be verified against an owned Figma file or approved brand source before being treated as canonical.
+
+Historical system maps, dot fields, connector lines, broad secondary colours, and texture are valid reference evidence, but are not default production rules. Use them only where they make the central concept clearer.

Wugweb_Brand_OS_Foundation/DECISIONS.md

@@ -11,6 +11,12 @@
 - Keep the palette limited per artwork
 - Use asymmetrical editorial balance
 - Communicate through metaphor, not text
+- Select one visual mode before composition: editorial thought leadership, campaign collage, product proof, systems/architecture, or typographic presentation.
+- Use physical paper/cards as tangible objects when meaningful; avoid fake torn-paper overlays and heavy grain as default treatments.
+- Use typography as a visual object in poster, campaign, and presentation formats; exclude explanatory copy from no-text thumbnails and article art.
+- Use a human or hand only when it clarifies agency, judgement, or interaction. A human is not mandatory in every asset.
+- Use blue as an available structural colour, not a mandatory colour in every composition.
+- Treat exact hex codes as provisional until an owned brand-token source is added.
 
 ## Banned
 - AI brains
@@ -21,3 +27,9 @@
 - Overly detailed illustrations
 - Gradient-heavy AI aesthetics
 - Excessive clutter
+- Copying an external studio's signature composition or visual asset
+
+## Conditional, not default
+- Dense system maps, dot fields, grids, and connectors: use only when the story is genuinely about systems, architecture, routes, or relationships.
+- One realistic UI or device proof: use when product experience is the evidence; do not add UI just to make an image feel technological.
+- Dark backgrounds: use for contrast or conceptual intensity; warm/light backgrounds are the normal editorial default.

Wugweb_Brand_OS_Foundation/README.md

@@ -20,6 +20,15 @@ Reference → Observation → Pattern → Principle → Rule → Prompt → Artw
 - Use asymmetrical editorial balance.
 - Communicate through metaphor, not text.
 
+## Non-negotiable interpretation rules
+
+- A Wugweb asset is not one fixed look. Select the visual mode first: editorial thought leadership, campaign collage, product proof, systems/architecture, or typographic presentation.
+- Core colour roles are stable; the permitted campaign palette is broader. Do not invent a hue, but do not force every core colour into every asset.
+- A real person, object, device, or UI module is used only when it advances the metaphor. The hero object normally carries the visual weight.
+- Text inside the artwork is format-dependent. It is usually excluded from article thumbnails, but may be the primary graphic object in posters, presentations, and campaign collateral.
+
+See `02_VISUAL_SYSTEM/21_VISUAL_MODES.md`, `05_REFERENCE_LIBRARY/16_PROJECT_SOURCE_INVENTORY.md`, and `09_VALIDATION/06_SOURCE_AND_RIGHTS.md`.
+
 ## Related files
 - CURRENT_CONTEXT.md
 - TODO.md