design-canvas-plugin-foundrytize

v0.1.4

Published

5 days ago

Scans a Fluent 2 app and shows what needs to change to match the Foundry design system — with live before/after toggle, annotated findings, and GitHub issue + Copilot fix actions.

0High
0Medium
0Low

unthink

design-canvas plugin foundrytize foundry fluent theme migration

Foundrytize

A Design Canvas plugin that scans Fluent 2 applications against the Foundry design system. It surfaces every token mismatch, component gap, and typography issue — then lets you preview the Foundry theme live, tweak individual elements, verify compliance, and package findings as GitHub issues with Copilot fix actions.

Features

Preflight Checks — Validates page readiness before applying any theme (FluentProvider presence, CSS layer order, Aptos font availability, inline overrides, hardcoded values)
Full-Page Scan — Analyzes tokens, components, fonts, CSS layers, custom variables, and data-viz tokens in one pass
Live Theme Preview — Toggle between Original, Foundry Dark, and Foundry Light overlays in real time
Element Inspector — Pick any element on the page, view its computed styles, and apply token overrides at element, type, or global scope
Token Map — Side-by-side comparison of every design token's original value vs. its Foundry override, with color swatches and diff highlighting
Compliance Verification — Post-application engine that checks every computed CSS value against Foundry spec with intelligent color-format matching
Readiness Score — 0–100 gauge with threshold-driven coloring (green ≥ 80, amber 40–79, red < 40)
GitHub Issue Packaging — One-click issue creation per finding or bulk-package grouped findings, with optional Copilot assignment
Markdown Export — Full scan report with summary stats, category breakdowns, and per-finding detail
Multi-Page Tracking — Accumulates findings across navigations for SPAs and multi-route apps

Installation

See the Installing Plugins guide for setup instructions.

How It Works

Pipeline

Preflight → Scan → Inspect / Tweak → Verify → Export / Create Issues

Preflight — Runs 7 readiness checks against the host page. Blockers (e.g., missing FluentProvider) prevent theme activation. Warnings (e.g., hardcoded colors) are surfaced for review.
Scan — Four scanners run in parallel against the host DOM:
- Token Scanner — Reads CSS custom properties from .fui-FluentProvider and compares against 150+ Foundry token targets. Brand tokens are critical; neutrals are warnings.
- Component Scanner — Detects fui-* component instances and validates Foundry-specific props (circular buttons, filled-darker inputs).
- Font Scanner — Verifies Aptos font family for body text and Aptos Mono for code/monospace elements.
- CSS Scanner — Checks @layer griffel, common declaration, custom variables on :root, and next-gen color aliases.
Inspect / Tweak — Pick any element to inspect its computed styles. Apply overrides at three scopes:
- Element — Single element only
- Type — All instances of the same component class
- Global — Design token value everywhere
Verify — Runs compliance rules against the live DOM after theme application. Smart matching handles color format differences (hex/rgb/hsl), browser-computed values, and lightness tolerance.
Export — Package findings as a Markdown report or create GitHub issues (individually or in bulk) with full context for Copilot-assisted fixes.

Theme Overlay Architecture

Three independent <style> layers are injected into the host page's <head>:

| Layer | Source | Purpose | |---|---|---| | Main overlay | themeOverlay.ts | Foundry tokens + component CSS + font injection | | Element overrides | elementOverlayCSS.ts | Per-element token swaps from Tweak tab | | Inspector overrides | elementOverlayCSS.ts | Live type-scoped and global tweaks |

All layers use a DC_EXCLUDE selector to avoid styling Design Canvas's own UI.

Plugin Tabs

Overview

The landing tab with readiness gauge, theme mode selector (Original / Foundry Dark / Foundry Light), scan button, preflight card, category badges, severity summary, and scanned-pages tracker.

Tweak

Element-level inspector. Click "Pick Element" to activate a hover-highlight overlay on the host page. Select an element to see its component spec, computed styles, and editable token fields. Changes apply live and are recorded as annotations.

Findings

Two view modes for reviewing scan results:

Grouped — Annotations rolled up into logical groups (e.g., "Button shape issues"). Bulk actions: Create Issue, Assign to Copilot, Package All as Issues.
Flat — Individual annotation cards with severity badge, current/expected values with color swatches, and per-finding actions.

Tokens

Searchable table showing every Fluent token with its original (pre-overlay) and Foundry values side-by-side. Color swatches for visual comparison, diff highlighting for changed rows, and a light/dark toggle to inspect both theme variants.

Verify

Post-application compliance dashboard. Runs verification rules and displays a score gauge, pass/fail/skip stats, and per-rule result rows sorted by failures first. Failed rules show actual vs. expected values with element counts.

Foundry Design System Reference

Brand Palette

Foundrytize maps the Foundry purple brand palette (shades 10–160) with primary accent at shade 70 (#643FB2). The full palette is defined in src/foundry/brandPalette.ts.

Token Targets

150+ token overrides across two themes defined in src/foundry/tokenTargets.ts:

| Category | Examples | |---|---| | Brand | colorBrandBackground, colorBrandForeground*, colorCompoundBrand* | | Neutral | colorNeutralBackground1–6, colorNeutralForeground1–4, colorNeutralStroke1–3 | | Status | colorStatusSuccess*, colorStatusWarning*, colorStatusDanger* | | Typography | fontFamilyBase → Aptos, sans-serif | | Shadows | shadow2, shadow4, shadow8, shadow16, shadow28, shadow64 | | Custom | --spacing-*, --radius-*, --content-width | | Data Viz | Custom spacing and color variables for chart components |

Component Map

40+ Fluent components mapped to Foundry wrappers with validation rules. Key enforcements:

Button — Must have circular shape (border-radius ≥ 50%)
Input — Must use filled-darker appearance (opaque background, no border)
Card, Dialog, Badge, Switch, Checkbox, Tab, Accordion — Brand color and typography overrides

Full map in src/foundry/componentMap.ts.

Development

Dev Harness

A local development environment that simulates the Design Canvas plugin context:

npm run dev:ui

Opens at http://localhost:5174 with a split-pane layout — simulated app canvas on the left, plugin panel on the right. Supports HMR for rapid iteration.

The harness (dev/harness.ts) provides mock implementations of PluginContext, notification services, storage, clipboard, and element picker.

Build

npm run build

Produces an ESM bundle at dist/index.js with TypeScript declarations. Uses tsup with design-canvas/* imports rewritten to @design-canvas/toolbox/* and marked external.

Scripts

| Script | Description | |---|---| | npm run build | Production build via tsup | | npm run dev:ui | Start Vite dev server with harness | | npm run preflight | Run plugin structure preflight checks | | npm run verify | Verify plugin meets Design Canvas conventions |

Architecture

src/
├── index.ts                  # Plugin entry point & event routing
├── store.ts                  # Reactive state management (no framework)
├── annotations/
│   └── types.ts              # Annotation, ScanSummary, severity/category types
├── foundry/
│   ├── brandPalette.ts       # Foundry purple shade map (10–160)
│   ├── componentMap.ts       # fui-* → Foundry wrapper catalog
│   ├── componentOverrides.ts # Component-level CSS overrides
│   ├── elementOverlayCSS.ts  # Per-element & inspector style layers
│   ├── overrideTargets.ts    # Token override option catalog
│   ├── themeOverlay.ts       # Main theme CSS injection
│   ├── tokenTargets.ts       # Light/dark token value definitions
│   └── verificationRules.ts  # Compliance rule definitions
├── inspector/
│   └── pickMode.ts           # Element picking overlay & selector generation
├── scanner/
│   ├── scan.ts               # Orchestrates all scanners
│   ├── tokenScanner.ts       # CSS custom property analysis
│   ├── componentScanner.ts   # Component detection & prop validation
│   ├── fontScanner.ts        # Aptos font family checks
│   ├── cssScanner.ts         # CSS layer & variable audit
│   └── preflight.ts          # Pre-scan readiness checks
├── utils/
│   ├── export.ts             # Markdown report generation
│   ├── github.ts             # GitHub issue body formatting
│   ├── hostDoc.ts            # Host page document accessor
│   └── issueFormatter.ts     # Annotation → issue formatting
├── verify/
│   └── verifyEngine.ts       # Post-application compliance engine
└── views/
    ├── OverviewTab.ts         # Dashboard with gauge & controls
    ├── TweakTab.ts            # Element inspector & live tweaks
    ├── AnnotationsTab.ts      # Grouped & flat finding views
    ├── TokenMapTab.ts         # Before/after token diff table
    ├── VerifyTab.ts           # Compliance check results
    ├── InspectorPanel.ts      # Component-specific token editor
    ├── PreflightCard.ts       # Preflight results card
    ├── ScannedPagesTracker.ts # Multi-page scan tracking
    └── theme.ts               # ThemeColors for plugin UI

Key Design Decisions

Zero runtime dependencies — Only @design-canvas/toolbox as a peer dependency
No framework — Store-driven rendering with manual DOM updates and event delegation
Shadow DOM aware — All host-page access goes through getHostDoc() to cross the iframe boundary
Non-destructive — Theme overlays are injected <style> tags that can be removed without side effects
Inline styles — Plugin UI uses inline styles with ThemeColors tokens since it renders inside a shadow DOM where external stylesheets don't apply

License

MIT