enterprise-ui-architect-cli 2.2.0 → 2.2.1

package/assets/SKILL.md

@@ -1,3 +1,11 @@
+---
+name: enterprise-ui-architect
+description: >
+  AI skill for building premium enterprise admin dashboards with MUI v7,
+  design system intelligence, backend integration patterns, package import
+  verification, and translation discipline.
+---
+
 # Enterprise UI Architect
 
 ## Description
@@ -96,6 +104,39 @@ design-system/
 
 When building a specific page, check for page overrides first, then fall back to MASTER.
 
+### Brief Inference (Taste Skill v2)
+Before generating, infer the design direction from the project context:
+- **Industry** — fintech, healthcare, logistics, SaaS, e-commerce, government
+- **Audience** — internal admins, external bidders, mixed roles, public citizens
+- **Mood** — authoritative, calm, urgent, playful, clinical, luxury
+- **Motion Depth** — static (government), subtle (SaaS), moderate (fintech), expressive (consumer)
+- **Layout Family** — dense data-grid, card-heavy, wizard/stepper, kanban, map+sidebar
+
+Use these inferences to weight the generated design system. Do not apply a generic template.
+
+### Design System Map
+Choose the underlying system based on context, not habit:
+
+| Context | Recommended System | Why |
+|---|---|---|
+| Enterprise admin, dense tables, form-heavy | MUI v7 (native) | Best token coverage, density, accessibility |
+| Consumer app, marketing pages, landing | shadcn/ui + Tailwind | Composable, modern aesthetics, fast iteration |
+| Government, compliance, accessibility-first | USWDS / GOV.UK | WCAG 2.2 AA baked in, proven patterns |
+| Microsoft ecosystem, Office-like | Fluent UI | Native ecosystem integration |
+| IBM/enterprise data viz | Carbon Design | Data-heavy, scientific precision |
+| Shopify ecosystem | Polaris | E-commerce native patterns |
+| GitHub/developer tools | Primer | Developer-centric density |
+| Bootstrap legacy migration | Bootstrap 5 | Gradual migration path |
+
+When in doubt, default to MUI v7 for admin dashboards. Never mix two full systems on the same page.
+
+### Dark Mode Protocol
+Dual-mode by default. Generate dark mode alongside light mode for every new page:
+- Use `alpha()` for overlays and borders, not hardcoded hex
+- Ensure contrast and hierarchy parity across themes
+- Test Skeleton loaders in both modes
+- Verify focus rings remain visible in dark mode
+
 ## Component Stack
 - **UI Components**: `@mui/material` v7
 - **Forms**: `react-hook-form` + `Controller`
@@ -138,7 +179,8 @@ Enterprise admin panels support configurable layout modes:
 - Footer content width independent of main content width
 
 ## Theme Augmentation
-MUI v7 requires module augmentation for custom variants and theme properties:
+MUI v7 requires module augmentation for custom variants and theme properties.
+**`tonal` is a custom variant, not native to MUI v7.** Every augmented variant must have a corresponding `theme.components` definition or the component will render without styles.
 
 ```typescript
 // types.ts
@@ -163,6 +205,27 @@ declare module '@mui/material/Pagination' {
 }
 ```
 
+**Required theme override for `tonal`:**
+```typescript
+// theme.ts
+const theme = createTheme({
+  components: {
+    MuiButton: {
+      variants: [
+        {
+          props: { variant: 'tonal' },
+          style: {
+            backgroundColor: 'rgba(0, 0, 0, 0.08)',
+            color: 'inherit',
+            // add your tonal styles here
+          },
+        },
+      ],
+    },
+  },
+});
+```
+
 Custom theme properties:
 ```typescript
 declare module '@mui/material/styles' {
@@ -243,7 +306,7 @@ python scripts/search.py --query "fintech" --domain industries -n 1
 ```
 
 ## UI Styles for Admin Dashboards
-The skill includes 15 admin-appropriate UI styles:
+The skill includes 10 admin-appropriate UI styles:
 
 | Style | Best For | Suitability |
 |---|---|---|
@@ -297,8 +360,8 @@ Common admin chart patterns:
 - **Geographic**: Map, Choropleth
 - **Correlation**: Scatter Plot, Heatmap
 
-## Pre-Delivery Checklist
-Every page must pass these checks before shipping:
+## Functional QA Checklist (Pre-Delivery)
+Every page must pass these functional checks before shipping. For motion, prose, and anti-slop validation, run the **Craft & Motion Audit** after this checklist.
 
 ### Universal Checks (All Pages)
 - [ ] All interactive elements have hover states and cursor-pointer
@@ -398,17 +461,20 @@ When backend is not available:
 | GraphQL + subscriptions | Apollo Client subscriptions or TanStack Query polling |
 
 ## Operating Modes
-Support these modes:
-- Implementation
-- Review
-- Refactor
-- Planning / Architecture
-- Design System Generation
-- Data Source Integration
-- Cursor Prompt Generation
+The skill adapts its output based on the current mode. When a mode is active, apply the corresponding rules:
+
+- **Implementation**: Full component code, props, styles, and tests. Assume backend API exists.
+- **Review**: Structured critique using the Review Output Format. No new code unless fixing a flagged issue.
+- **Refactor**: Preserve working patterns; modernize with explicit levers. Document each change.
+- **Planning / Architecture**: High-level structure, file layout, state management decisions, and API contract suggestions.
+- **Design System Generation**: Theme tokens, component primitives, and pattern library. No business logic.
+- **Data Source Integration**: Adapter functions, TanStack Query hooks, loading/error/empty states.
+- **Cursor Prompt Generation**: Concise, copy-pasteable prompts for .cursorrules or AI chat.
 
 ## Page Pattern Mapping
-Include detailed guidance for:
+> **TODO:** Full guidance for each page type is planned but not yet implemented. Until then, use the component standards and Functional QA Checklist above, plus industry-specific patterns from the data files.
+
+Planned page types:
 - CRUD List Page
 - Complex Form Page
 - Dashboard Page
@@ -418,15 +484,6 @@ Include detailed guidance for:
 - Auth Page
 - Blank Layout
 
-For each page type, include:
-- Visual pattern
-- MUI architectural equivalent
-- reusable components
-- required states
-- accessibility requirements
-- responsive behavior
-- anti-patterns
-
 ## Drawer vs Dialog vs Page Rules
 Use Dialog for:
 - delete confirmation
@@ -456,14 +513,14 @@ Every production table should use `@tanstack/react-table` and support:
 - sorting
 - filtering (faceted + global)
 - search (debounced 500ms)
-- pagination via MUI `Pagination` (`shape='rounded'` `variant='tonal'`)
+- pagination via MUI `Pagination` (`shape='rounded'` `variant='tonal'` — custom, see Theme Augmentation)
 - server-side pagination when needed
 - loading state
 - empty state
 - error state
 - row actions via `OptionMenu`
 - optional bulk actions via `rowSelection`
-- status chips via MUI `Chip` (`variant='tonal'`)
+- status chips via MUI `Chip` (`variant='tonal'` — custom, see Theme Augmentation)
 - formatted date/number values
 - responsive behavior (horizontal scroll)
 - accessible headers
@@ -510,7 +567,7 @@ Avoid:
 - one-off shadows
 - heavy inline `sx` props on generic primitives
 - business-specific styling inside generic UI primitives
-- using `item` prop on MUI v7 `Grid`
+- using legacy `Grid` `item` prop; prefer `Grid2` (unstable) with `size` props
 
 ## Package Import Discipline
 
@@ -610,6 +667,41 @@ Before marking a feature complete:
 - [ ] No hardcoded user-facing strings remain
 - [ ] `enterprise-ui verify-i18n` passes with zero missing keys
 
+## Browser UI Audit
+Use the CLI `audit-ui` command to automatically verify pages in a headless browser before shipping:
+
+```bash
+npx enterprise-ui audit-ui --url http://localhost:3000 --routes /,/az/login --output ./ui-audit
+```
+
+This command:
+1. Launches a headless Chromium browser
+2. Navigates to each specified route
+3. Captures full-page screenshots
+4. Collects console errors and warnings
+5. Runs automated checks:
+   - Page title present and meaningful
+   - Viewport meta tag exists
+   - All images have `alt` or `aria-hidden`
+   - All buttons have accessible names
+   - All links have `href` and accessible text
+   - All form inputs have associated labels
+   - No console errors or warnings
+6. Writes a markdown report to `./ui-audit/audit-report.md`
+
+### When to run
+- After every significant page refactor
+- Before opening a pull request
+- After dependency updates that might affect rendering
+- When verifying responsive layouts at different viewports
+
+### CI integration
+Add to your test pipeline:
+```bash
+npx enterprise-ui audit-ui --url http://localhost:3000 --routes /,/admin,/login
+```
+The command exits with code 1 if any route fails checks, making it suitable for CI gates.
+
 ## Keyboard Navigation
 MUI components require specific keyboard patterns:
 
@@ -626,6 +718,120 @@ MUI components require specific keyboard patterns:
 | Menu | Arrow keys navigate items; Escape closes; Enter activates |
 | Dialog | Escape closes; Tab traps focus; Return focus to trigger on close |
 
+## Motion Design Principles
+> Motion principles inspired by [Emil Kowalski](https://emilkowalski.xyz/).
+
+When implementing animations and transitions, apply this frequency-based decision framework:
+
+### 1. Should this animate at all?
+| Frequency | Decision |
+|---|---|
+| 100+ times/day (keyboard shortcuts, command palette) | No animation. Ever. |
+| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
+| Occasional (modals, drawers, toasts) | Standard animation |
+| Rare/first-time (onboarding, celebrations) | Can add delight |
+
+### 2. Timing Guardrails
+Keep UI animations under 300ms. Perceived performance matters as much as actual speed.
+
+| Element | Duration |
+|---|---|
+| Button press feedback | 100–160ms |
+| Tooltips, small popovers | 125–200ms |
+| Dropdowns, selects | 150–250ms |
+| Modals, drawers | 200–500ms |
+| Marketing / explanatory | Can be longer |
+
+### 3. Easing Selection
+Never use `ease-in` for UI animations — it starts slow and feels sluggish. Use custom curves:
+
+```css
+/* Strong ease-out for UI interactions */
+--ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+
+/* Strong ease-in-out for on-screen movement */
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+
+/* iOS-like drawer curve */
+--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
+```
+
+### 4. Implementation Rules
+- Only animate `transform` and `opacity` — GPU-composited, no layout/paint
+- Never animate from `scale(0)` — start from `scale(0.95)` with `opacity: 0`
+- Use CSS transitions (not keyframes) for interruptible UI states
+- Add `transform: scale(0.97)` on `:active` for press feedback
+- Make popovers origin-aware: scale from trigger, not center (modals stay centered)
+- Respect `prefers-reduced-motion`: fewer and gentler animations, not zero
+- Gate hover animations behind `@media (hover: hover) and (pointer: fine)`
+
+## Prose Discipline
+> Prose discipline adapted from the **Impeccable** skill (editorial brief: denylist, throat-clearing bans, verbs-lead rule).
+
+When writing documentation, CHANGELOG entries, commit messages, or skill output:
+
+### Principles
+1. **Concrete over comprehensive.** Coverage is an AI obsession. Trade coverage for momentum. Leave things out.
+2. **Verbs lead. Nouns follow.** Imperative is fine. Active voice.
+3. **Name names. Use numbers.** Real file paths, real version numbers, real benchmarks. Cut "lightweight"; write "54 KB".
+4. **Vary sentence length on purpose.** Long, long, short. Smooth uniform rhythm is the deepest AI tell.
+5. **Read it aloud. Fix anything you stumble over.**
+
+### Denylist — Banned AI-Tell Words
+Never use these in user-facing prose:
+
+| Banned | Use instead |
+|---|---|
+| `delve`, `delves`, `delving` | "Look at", "explore", or delete the throat-clearing verb |
+| `robust`, `robustness` | Cite the failure mode handled |
+| `seamless`, `seamlessly` | Say what specifically works without friction |
+| `elevate`, `elevates` | Use the specific verb (improve, raise, sharpen) |
+| `empower`, `empowers` | "Let you", "make possible" |
+| `underscore`, `underscores` | "Show", "make clear" |
+| `pivotal` | "Central", "key", or describe the role |
+| `tapestry` | Cut entirely |
+
+### Throat-Clearing Bans
+Cut these openers and closers:
+- "In today's ..."
+- "Gone are the days"
+- "Whether you're ..."
+- "Let's dive in"
+- "In summary", "In conclusion"
+- "Moreover", "Furthermore"
+
+## Craft & Motion Audit (Pre-Flight Checklist)
+Every output — page, component, or refactor — must honestly pass every checkbox before shipping. This audit covers motion discipline, prose quality, and anti-slop validation. Run it **after** the Functional QA Checklist.
+
+### Motion Audit
+- [ ] No animation on keyboard-initiated actions used 100+ times/day
+- [ ] All UI animations ≤ 300ms
+- [ ] No `ease-in` on UI elements
+- [ ] No `transition: all` — exact properties specified
+- [ ] No `scale(0)` entrances
+- [ ] `prefers-reduced-motion` respected
+- [ ] Only `transform` and `opacity` animated
+
+### Prose Audit
+- [ ] No denylist words in user-facing text
+- [ ] No throat-clearing openers/closers
+- [ ] Concrete numbers where possible
+- [ ] Verbs lead, active voice
+
+### Anti-Slop Validation
+- [ ] No generic AI-tool glow, glassmorphism, or neon gradients unless explicitly requested
+- [ ] No placeholder text, Lorem Ipsum, or "sample data" in shipped output
+- [ ] No half-finished sections — complete or remove
+- [ ] Component primitives used before inventing new classes
+- [ ] Design tokens used instead of hardcoded values
+
+### Redesign Protocol (existing projects)
+When refactoring an existing page:
+1. Audit first — identify structural and visual problems before changing code
+2. Preserve working patterns — do not break existing user flows
+3. Modernize with explicit levers — document each change and why
+4. Run the hard pre-flight check before finalizing
+
 ## Review Output Format
 When reviewing implementation, always output:
 

package/assets/data/anti-patterns.csv

@@ -56,3 +56,8 @@ id,area,bad_pattern,why_bad,fix
 55,Dependencies,Adding new imports without verifying the package is installed,Build fails in CI or for teammates TypeScript errors runtime crashes silent failures,Always check package.json before adding an import If package is missing ask user for confirmation then install with the correct package manager
 57,Dependencies,Adding translation keys in source code without updating all locale files,Users see raw keys or missing text in unsupported languages breaks i18n contract,When adding t(key) always add the key to every messages locale file Run verify-i18n to check
 56,i18n,Adding translation keys in code without updating all locale files,Users see raw keys or missing text in unsupported languages breaks i18n contract,When adding t(key) always add the key to every messages locale file Run verify-i18n to check
+58,Motion,Animating UI elements with duration over 300ms,Feels sluggish and unresponsive degrades perceived performance especially on repeated interactions,Keep UI animations under 300ms use 100-160ms for button feedback 150-250ms for dropdowns
+59,Motion,Using ease-in easing on UI animations,Starts slow making the interface feel sluggish and unresponsive users watch the initial moment most closely,Always use ease-out or custom cubic-bezier for UI animations never ease-in
+60,Motion,Using transition all instead of exact properties,Triggers layout and paint on properties that should not animate hurts performance and causes visual glitches,Specify exact properties transition transform 200ms ease-out opacity 200ms ease-out
+61,Motion,Animating elements from scale 0,Nothing in the real world appears from nothing looks artificial and jarring,Start from scale 0.95 combined with opacity 0 for natural entrances
+62,Motion,Animating padding margin width or height,Triggers layout recalculation and paint severe performance impact especially on scroll or resize,Only animate transform and opacity they are GPU-composited and skip layout

package/assets/data/industries.csv

@@ -1,16 +1,16 @@
-id,industry,display_name,pattern,style_priority,color_mood,typography_mood,key_effects,anti_patterns
-1,saas,SaaS / B2B Platform,Feature-Rich Dashboard + Onboarding,bento-grid minimalism soft-ui,Clean blues + white + accent purple,Inter / Public Sans sans-serif,Micro-interactions smooth transitions 200ms subtle shadows,Skeuomorphism bright neon colors cluttered hero slow animations
-2,fintech,Fintech / Banking,Data-Dense Dashboard + Transaction Table,minimalism dark-mode glassmorphism,Deep navy + emerald green + gold accents,Plus Jakarta Sans / DM Sans modern geometric,Real-time data updates subtle pulse animations card hover elevation,Playful colors rounded corners everywhere emoji icons insufficient contrast
-3,healthcare,Healthcare / Medical,Patient List + Appointment Calendar + Charts,minimalism accessible soft-ui,Soft teal + white + warm gray + alert red,Open Sans / Roboto highly readable,Clear visual hierarchy status badges with icons gentle transitions,Small text poor contrast complex medical jargon without tooltips missing loading states
-4,ecommerce,E-commerce Admin,Order Management + Inventory Grid + Sales Charts,bento-grid data-dense,Orange accent + white + dark sidebar + success green,Inter / Source Sans Pro clean functional,Quick actions contextual menus real-time stock indicators,Bright sales-y colors distracting animations missing empty states for out-of-stock
-5,logistics,Logistics / Supply Chain,Map + Shipment Tracker + Fleet Table,real-time glassmorphism,Deep blue + bright cyan + warning amber + map green,Roboto Mono / Inter monospace for tracking IDs,Map integrations timeline views live status indicators,Cluttered maps poor mobile experience missing offline indicators
-6,hr,HR / People Management,Employee Directory + Org Chart + Payroll Table,minimalism soft-ui bento-grid,Warm purple + soft gray + white + status colors,Work Sans / Lato friendly professional,Profile cards org tree visualizations approval workflows,Overly casual fonts missing privacy indicators complex navigation too many clicks
-7,crm,CRM / Sales,Pipeline Board + Contact List + Activity Feed,bento-grid soft-ui,Electric blue + white + warm gray + deal stage colors,Inter / SF Pro clean crisp,Drag-drop pipeline activity timelines win/loss indicators,Missing empty pipeline states poor mobile card layout overwhelming notifications
-8,erp,ERP / Manufacturing,Production Dashboard + Inventory + BOM Table,data-dense executive,Industrial gray + safety orange + machine blue + alert red,IBM Plex Sans / Roboto technical precise,Machine status gauges production line visuals alert banners,Overly decorative fonts cluttered tables missing real-time indicators slow refresh
-9,education,Education / LMS,Course List + Student Progress + Gradebook,minimalism accessible soft-ui,Academic blue + warm white + success green + caution amber,Lora / Open Sans readable elegant,Progress bars achievement badges calendar views,Childish fonts excessive gamification poor accessibility missing progress persistence
-10,government,Government / Public Sector,Case Management + Document List + Reporting,minimalism accessible,Official blue + white + gray + priority red,Merriweather / Open Sans formal trustworthy,Clear status workflows document version tracking audit trails,Political colors overly modern flashy design missing WCAG compliance complex language
-11,cybersecurity,Cybersecurity / SOC,Alert Feed + Threat Map + Incident Table,dark-mode ai-native,Deep black + alert red + cyber cyan + warning amber,Fira Code / Inter monospace for logs technical,Dark theme real-time alerts threat level indicators SOC timeline,Light theme by default poor alert visibility cluttered dashboards missing severity colors
-12,real-estate,Real Estate / Property,Property Grid + Map + Lead Pipeline,bento-grid soft-ui,Premium navy + gold accent + white + status green,Playfair Display / Inter luxury clean,Property cards map pins lead scoring visual comparison tools,Excessive imagery poor table performance missing price formatting cluttered filters
-13,energy,Energy / Utilities,Grid Monitor + Meter Readings + Outage Map,real-time data-dense,Power blue + grid yellow + outage red + eco green,Roboto / Source Sans Pro technical functional,Real-time gauges geographic outage maps consumption charts,Missing time-series data poor mobile map experience slow data refresh
-14,media,Media / Content Management,Asset Library + Editorial Calendar + Analytics,minimalism bento-grid,Dark charcoal + vibrant accent + white + video red,Montserrat / Inter modern dynamic,Media previews drag-drop upload editorial timeline engagement charts,Cluttered asset grids missing metadata poor search missing preview thumbnails
-15,nonprofit,Nonprofit / NGO,Donor CRM + Campaign Tracker + Impact Dashboard,soft-ui accessible minimalism,Hope blue + growth green + warm white + heart red,Merriweather / Lora trustworthy warm,Donor profiles campaign progress impact visualization volunteer management,Overly corporate design missing donation CTAs poor mobile donation flow complex reporting
+id,industry,display_name,pattern,style_priority,color_mood,typography_mood,key_effects,anti_patterns,motion_depth,brief_inference
+1,saas,SaaS / B2B Platform,Feature-Rich Dashboard + Onboarding,bento-grid minimalism soft-ui,Clean blues + white + accent purple,Inter / Public Sans sans-serif,Micro-interactions smooth transitions 200ms subtle shadows,Skeuomorphism bright neon colors cluttered hero slow animations,subtle,SaaS buyers expect calm professional interfaces with clear value proposition and self-serve onboarding
+2,fintech,Fintech / Banking,Data-Dense Dashboard + Transaction Table,minimalism dark-mode glassmorphism,Deep navy + emerald green + gold accents,Plus Jakarta Sans / DM Sans modern geometric,Real-time data updates subtle pulse animations card hover elevation,Playful colors rounded corners everywhere emoji icons insufficient contrast,subtle,Users manage money trust and precision matter every pixel signals security and compliance
+3,healthcare,Healthcare / Medical,Patient List + Appointment Calendar + Charts,minimalism accessible soft-ui,Soft teal + white + warm gray + alert red,Open Sans / Roboto highly readable,Clear visual hierarchy status badges with icons gentle transitions,Small text poor contrast complex medical jargon without tooltips missing loading states,static,Clinical environments demand readability accessibility and calm confidence errors have real consequences
+4,ecommerce,E-commerce Admin,Order Management + Inventory Grid + Sales Charts,bento-grid data-dense,Orange accent + white + dark sidebar + success green,Inter / Source Sans Pro clean functional,Quick actions contextual menus real-time stock indicators,Bright sales-y colors distracting animations missing empty states for out-of-stock,subtle,Operators need speed and density they process hundreds of orders daily every click must feel instant
+5,logistics,Logistics / Supply Chain,Map + Shipment Tracker + Fleet Table,real-time glassmorphism,Deep blue + bright cyan + warning amber + map green,Roboto Mono / Inter monospace for tracking IDs,Map integrations timeline views live status indicators,Cluttered maps poor mobile experience missing offline indicators,moderate,Dispatchers work under time pressure live data is mission-critical mobile field access is essential
+6,hr,HR / People Management,Employee Directory + Org Chart + Payroll Table,minimalism soft-ui bento-grid,Warm purple + soft gray + white + status colors,Work Sans / Lato friendly professional,Profile cards org tree visualizations approval workflows,Overly casual fonts missing privacy indicators complex navigation too many clicks,subtle,HR users handle sensitive personal data privacy cues and trust signals must be immediate and obvious
+7,crm,CRM / Sales,Pipeline Board + Contact List + Activity Feed,bento-grid soft-ui,Electric blue + white + warm gray + deal stage colors,Inter / SF Pro clean crisp,Drag-drop pipeline activity timelines win/loss indicators,Missing empty pipeline states poor mobile card layout overwhelming notifications,subtle,Salespeople live in this tool all day speed of data entry and visual pipeline clarity directly affect revenue
+8,erp,ERP / Manufacturing,Production Dashboard + Inventory + BOM Table,data-dense executive,Industrial gray + safety orange + machine blue + alert red,IBM Plex Sans / Roboto technical precise,Machine status gauges production line visuals alert banners,Overly decorative fonts cluttered tables missing real-time indicators slow refresh,static,Factory floor and warehouse managers need dense data at a glance downtime costs money
+9,education,Education / LMS,Course List + Student Progress + Gradebook,minimalism accessible soft-ui,Academic blue + warm white + success green + caution amber,Lora / Open Sans readable elegant,Progress bars achievement badges calendar views,Childish fonts excessive gamification poor accessibility missing progress persistence,subtle,Educators and students span all ages and abilities inclusivity and clarity outweigh visual flair
+10,government,Government / Public Sector,Case Management + Document List + Reporting,minimalism accessible,Official blue + white + gray + priority red,Merriweather / Open Sans formal trustworthy,Clear status workflows document version tracking audit trails,Political colors overly modern flashy design missing WCAG compliance complex language,static,Citizens and civil servants need transparent trustworthy interfaces compliance and accessibility are non-negotiable
+11,cybersecurity,Cybersecurity / SOC,Alert Feed + Threat Map + Incident Table,dark-mode ai-native,Deep black + alert red + cyber cyan + warning amber,Fira Code / Inter monospace for logs technical,Dark theme real-time alerts threat level indicators SOC timeline,Light theme by default poor alert visibility cluttered dashboards missing severity colors,moderate,SOC analysts monitor threats 24/7 alert fatigue is real every second of delay matters
+12,real-estate,Real Estate / Property,Property Grid + Map + Lead Pipeline,bento-grid soft-ui,Premium navy + gold accent + white + status green,Playfair Display / Inter luxury clean,Property cards map pins lead scoring visual comparison tools,Excessive imagery poor table performance missing price formatting cluttered filters,subtle,Agents and brokers show properties to high-value clients the interface must feel premium and trustworthy
+13,energy,Energy / Utilities,Grid Monitor + Meter Readings + Outage Map,real-time data-dense,Power blue + grid yellow + outage red + eco green,Roboto / Source Sans Pro technical functional,Real-time gauges geographic outage maps consumption charts,Missing time-series data poor mobile map experience slow data refresh,moderate,Grid operators need millisecond-level awareness public outage maps must be instantly understandable
+14,media,Media / Content Management,Asset Library + Editorial Calendar + Analytics,minimalism bento-grid,Dark charcoal + vibrant accent + white + video red,Montserrat / Inter modern dynamic,Media previews drag-drop upload editorial timeline engagement charts,Cluttered asset grids missing metadata poor search missing preview thumbnails,subtle,Editors and producers work creatively the tool must get out of the way and handle large assets smoothly
+15,nonprofit,Nonprofit / NGO,Donor CRM + Campaign Tracker + Impact Dashboard,soft-ui accessible minimalism,Hope blue + growth green + warm white + heart red,Merriweather / Lora trustworthy warm,Donor profiles campaign progress impact visualization volunteer management,Overly corporate design missing donation CTAs poor mobile donation flow complex reporting,subtle,Donors and volunteers respond to heart and clarity the interface must inspire trust and action

package/assets/data/pre-delivery-checklist.csv

@@ -38,5 +38,13 @@ id,page_type,check,severity,why_it_matters
 37,dependencies,No unused imports or dead dependencies,Medium,Bloats bundle and confuses developers
 38,dependencies,Package manager lockfile is in sync with package.json,High,Prevents inconsistent installs across environments
 39,i18n,All translation keys exist in every locale file,High,Missing keys show raw text to users
+40,motion,No UI animation exceeds 300ms duration,High,Long animations feel sluggish and unprofessional
+41,motion,No ease-in easing used on interactive elements,High, ease-in feels sluggish and unresponsive
+42,motion,Only transform and opacity are animated,High,Other properties trigger layout and paint hurting performance
+43,motion,prefers-reduced-motion is respected for all motion,High,Accessibility for users with vestibular disorders
+44,prose,No denylist words in user-facing text or docs,Medium,AI-tell words degrade perceived quality and trust
+45,prose,No throat-clearing openers or closers in docs,Medium,Wastes reader time signals low-quality generated content
+46,anti-slop,No placeholder text or Lorem Ipsum in shipped output,Critical,Shipped code must be complete and production-ready
+47,anti-slop,Design tokens used instead of hardcoded colors everywhere,Critical,Hardcoded values break theming and consistency
 40,i18n,No hardcoded user-facing strings outside t() calls,High,Breaks multi-language support
 41,i18n,New translation keys added to all messages files before commit,High,Prevents incomplete translations

package/assets/data/styles.csv

@@ -1,16 +1,16 @@
-id,style_name,display_name,description,best_for,keywords,performance,accessibility,admin_suitability
-1,minimalism,Minimalism & Swiss Style,Clean whitespace crisp typography clear hierarchy no decorative elements,Enterprise dashboards data-heavy apps documentation,Whitespace grid system sans-serif clean lines neutral colors,Excellent,Excellent,10
-2,bento-grid,Bento Box Grid,Card-based modular layout grid with varied cell sizes dashboard widgets,Admin dashboards analytics product features status overview,Modular cards widgets grid layout information density snapping,Excellent,Excellent,10
-3,dark-mode,Dark Mode (OLED),Deep blacks with high contrast elements reduced eye strain night-friendly,DevOps monitoring cybersecurity night-shift operations coding platforms,OLED pure black high contrast neon accents reduced glare,Good,Good,9
-4,soft-ui,Soft UI Evolution,Rounded corners subtle shadows gentle gradients calming visual weight modern SaaS,HR healthcare wellness customer support non-technical users,Soft shadows rounded corners gentle gradients pastel tones calming,Excellent,Excellent,9
-5,glassmorphism,Glassmorphism,Translucent frosted glass effect with backdrop blur layered depth modern feel,Financial dashboards premium SaaS creative admin modern startups,Translucency blur backdrop-filter layered depth refraction light,Medium,Medium,7
-6,data-dense,Data-Dense Dashboard,Maximum information density compact tables inline charts minimal padding power user,Trading ERP manufacturing supply chain operations power users,Compact tables inline charts minimal whitespace high density monochrome,Good,Medium,10
-7,executive,Executive Dashboard,High-level KPIs summary cards trend sparklines minimal detail C-suite focused,C-suite executives board meetings quarterly reviews high-level overview,Large numbers trend arrows sparklines minimal text snapshot view,Excellent,Excellent,8
-8,real-time,Real-Time Monitoring,Live data streams pulse indicators auto-refreshing counters operational focus,DevOps IoT logistics network monitoring call centers operations,Live counters pulsing dots auto-refresh timelines real-time badges,Good,Good,9
-9,accessible,Accessible & Inclusive,High contrast large touch targets screen-reader optimized reduced motion,Government healthcare education public sector compliance-required,High contrast large fonts focus visible reduced motion screen-reader,Excellent,Excellent,10
-10,claymorphism,Claymorphism,3D-like soft extruded shapes inner shadows playful depth educational friendly,Educational admin nonprofit HR training platforms children's apps,Inner shadows soft 3D extrusion playful depth pastel colors rounded,Medium,Good,6
-11,ai-native,AI-Native UI,Chat-first interfaces prompt boxes streaming text avatar indicators agent focus,AI platforms chatbots copilot admin AI-powered analytics,Streaming text typing indicators avatar bubbles prompt interfaces,Medium,Medium,7
-12,neumorphism,Neumorphism,Soft extruded shapes that look like they push out from background subtle depth,Health wellness meditation minimalist admin soft aesthetic,Soft shadows extruded shapes monochrome subtle depth tactile feel,Medium,Medium,5
-13,brutalism,Brutalism,Raw unpolished high contrast bold typography unapologetic design artistic,Creative agencies design portfolios artistic admin experimental,High contrast bold borders raw typography unpolished expressive,Medium,Medium,3
-14,liquid-glass,Liquid Glass,Premium translucent surfaces with light refraction high-end aesthetic 2025+,Premium SaaS high-end e-commerce luxury admin high-visibility products,Refraction light caustics premium translucent depth high-end,Medium,Medium,6
-15,motion-driven,Motion-Driven,Animations guide attention transitions explain state changes storytelling,Portfolio admin storytelling dashboards onboarding flows walkthroughs,Smooth transitions scroll animations state change animations guides,Medium,Medium,6
+id,style_name,display_name,description,best_for,keywords,performance,accessibility,admin_suitability,motion_depth
+1,minimalism,Minimalism & Swiss Style,Clean whitespace crisp typography clear hierarchy no decorative elements,Enterprise dashboards data-heavy apps documentation,Whitespace grid system sans-serif clean lines neutral colors,Excellent,Excellent,10,static
+2,bento-grid,Bento Box Grid,Card-based modular layout grid with varied cell sizes dashboard widgets,Admin dashboards analytics product features status overview,Modular cards widgets grid layout information density snapping,Excellent,Excellent,10,subtle
+3,dark-mode,Dark Mode (OLED),Deep blacks with high contrast elements reduced eye strain night-friendly,DevOps monitoring cybersecurity night-shift operations coding platforms,OLED pure black high contrast neon accents reduced glare,Good,Good,9,subtle
+4,soft-ui,Soft UI Evolution,Rounded corners subtle shadows gentle gradients calming visual weight modern SaaS,HR healthcare wellness customer support non-technical users,Soft shadows rounded corners gentle gradients pastel tones calming,Excellent,Excellent,9,subtle
+5,glassmorphism,Glassmorphism,Translucent frosted glass effect with backdrop blur layered depth modern feel,Financial dashboards premium SaaS creative admin modern startups,Translucency blur backdrop-filter layered depth refraction light,Medium,Medium,7,moderate
+6,data-dense,Data-Dense Dashboard,Maximum information density compact tables inline charts minimal padding power user,Trading ERP manufacturing supply chain operations power users,Compact tables inline charts minimal whitespace high density monochrome,Good,Medium,10,static
+7,executive,Executive Dashboard,High-level KPIs summary cards trend sparklines minimal detail C-suite focused,C-suite executives board meetings quarterly reviews high-level overview,Large numbers trend arrows sparklines minimal text snapshot view,Excellent,Excellent,8,subtle
+8,real-time,Real-Time Monitoring,Live data streams pulse indicators auto-refreshing counters operational focus,DevOps IoT logistics network monitoring call centers operations,Live counters pulsing dots auto-refresh timelines real-time badges,Good,Good,9,moderate
+9,accessible,Accessible & Inclusive,High contrast large touch targets screen-reader optimized reduced motion,Government healthcare education public sector compliance-required,High contrast large fonts focus visible reduced motion screen-reader,Excellent,Excellent,10,static
+10,claymorphism,Claymorphism,3D-like soft extruded shapes inner shadows playful depth educational friendly,Educational admin nonprofit HR training platforms children's apps,Inner shadows soft 3D extrusion playful depth pastel colors rounded,Medium,Good,6,moderate
+11,ai-native,AI-Native UI,Chat-first interfaces prompt boxes streaming text avatar indicators agent focus,AI platforms chatbots copilot admin AI-powered analytics,Streaming text typing indicators avatar bubbles prompt interfaces,Medium,Medium,7,expressive
+12,neumorphism,Neumorphism,Soft extruded shapes that look like they push out from background subtle depth,Health wellness meditation minimalist admin soft aesthetic,Soft shadows extruded shapes monochrome subtle depth tactile feel,Medium,Medium,5,subtle
+13,brutalism,Brutalism,Raw unpolished high contrast bold typography unapologetic design artistic,Creative agencies design portfolios artistic admin experimental,High contrast bold borders raw typography unpolished expressive,Medium,Medium,3,expressive
+14,liquid-glass,Liquid Glass,Premium translucent surfaces with light refraction high-end aesthetic 2025+,Premium SaaS high-end e-commerce luxury admin high-visibility products,Refraction light caustics premium translucent depth high-end,Medium,Medium,6,moderate
+15,motion-driven,Motion-Driven,Animations guide attention transitions explain state changes storytelling,Portfolio admin storytelling dashboards onboarding flows walkthroughs,Smooth transitions scroll animations state change animations guides,Medium,Medium,6,expressive

package/assets/templates/base/skill-content.md

@@ -6,7 +6,7 @@ Guides AI coding assistants to build premium admin dashboards that use MUI v7 co
 ## Visual Direction (Enterprise Admin)
 - Card-based layouts with consistent padding and elevation
 - Sidebar + navbar composition (header 54px, sidebar 260px/71px collapsed)
-- Status chips with semantic colors and tonal variant
+- Status chips with semantic colors and tonal variant (custom — requires theme override)
 - Dashboard widget rhythm with 24px gaps
 - Polished tables with action menus (header 56px, body 50px, horizontal borders only)
 - Clean form sections with footer actions
@@ -16,7 +16,7 @@ Guides AI coding assistants to build premium admin dashboards that use MUI v7 co
 ## Implementation Engine (MUI v7)
 - MUI Card, CardHeader, CardContent, CardActions, Divider
 - MUI Dialog, Drawer, Button, Chip, TextField, Pagination
-- MUI Grid for responsive layouts (no `item` prop in v7)
+- MUI Grid2 for responsive layouts (legacy `Grid` `item` prop avoided)
 - MUI Tabs, Descriptions, Badge, Switch
 - Theme tokens via theme.palette, theme.spacing, theme.shape
 
@@ -73,7 +73,7 @@ python scripts/search.py --query "saas" --design-system --persist --product "MyA
 - Nonprofit / NGO
 
 ## UI Styles for Admin Dashboards
-15 styles rated for admin suitability:
+10 styles rated for admin suitability:
 - Minimalism & Swiss Style (10/10)
 - Bento Box Grid (10/10)
 - Dark Mode OLED (9/10)
@@ -167,7 +167,7 @@ Before building charts tables or forms detect the data source:
 - Using MUI TablePagination for logic instead of TanStack state
 - Using native MUI Table without TanStack react-table
 - Missing CardHeader/CardContent/CardActions structure
-- Using `item` prop on MUI v7 Grid
+- Using legacy `Grid` `item` prop; prefer `Grid2` with `size` props
 - Forgetting `declare module` for `tonal` variant
 - Using MUI v7 without AppRouterCacheProvider in Next.js
 - Using rules inline alongside schema resolver

package/assets/templates/platforms/copilot.json

@@ -12,7 +12,10 @@
     "Table Standard",
     "Form Standard",
     "Theme and Styling Standard",
-    "Review Output Format"
+    "Review Output Format",
+    "Motion Design Principles",
+    "Prose Discipline",
+    "Craft & Motion Audit (Pre-Flight Checklist)"
   ],
   "promptSuffix": "Before writing or editing UI code, inspect the existing codebase for PageLayout, Card, Table, Form, Drawer, Dialog, and StatusChip abstractions. Reuse existing conventions. Do not introduce unnecessary abstractions."
 }

package/assets/templates/platforms/cursor.json

@@ -16,7 +16,10 @@
     "Table Standard",
     "Form Standard",
     "Theme and Styling Standard",
-    "Review Output Format"
+    "Review Output Format",
+    "Motion Design Principles",
+    "Prose Discipline",
+    "Craft & Motion Audit (Pre-Flight Checklist)"
   ],
   "rules": [
     "Always inspect existing PageLayout, Card, Table, Form abstractions before creating new ones.",

package/assets/templates/platforms/windsurf.json

@@ -11,7 +11,10 @@
     "Table Standard",
     "Form Standard",
     "Theme and Styling Standard",
-    "Review Output Format"
+    "Review Output Format",
+    "Motion Design Principles",
+    "Prose Discipline",
+    "Craft & Motion Audit (Pre-Flight Checklist)"
   ],
   "rules": [
     "Inspect existing abstractions before adding new UI primitives.",

package/dist/commands/audit-ui.d.ts

@@ -6,7 +6,9 @@ export interface AuditOptions {
         width: number;
         height: number;
     };
+    timeout: number;
+    waitUntil: "load" | "domcontentloaded" | "networkidle";
 }
 export declare function parseAuditArgs(args: string[]): AuditOptions;
-export declare function auditUiCommand(options: AuditOptions): Promise<void>;
+export declare function auditUiCommand(options: AuditOptions): Promise<number>;
 //# sourceMappingURL=audit-ui.d.ts.map

package/dist/commands/audit-ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-ui.d.ts","sourceRoot":"","sources":["../../src/commands/audit-ui.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAuCD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CAuB3D;AAwFD,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAqJzE"}
+{"version":3,"file":"audit-ui.d.ts","sourceRoot":"","sources":["../../src/commands/audit-ui.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,aAAa,CAAC;CACxD;AAwCD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CAqC3D;AA2FD,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAiK3E"}