@caddis/cli 0.2.6 → 0.4.0

package/bundles/codex/.codex/skills/frontend/frontend-design/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications. Generates creative, polished code that avoids generic AI aesthetics while strictly adhering to the user's technical standards.
+---
+
+# Frontend Design Skill
+
+This skill guides the creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+## 1. Core Principle: Avoid "AI Slop"
+- **Typography:** Avoid system fonts (Inter, Arial, Roboto). Pair a distinctive display font (e.g., *Cormorant Garamond*, *Playfair Display*, *Space Mono*) with a refined, readable body font. Use dramatic scale jumps ($h1 > 5rem$ vs metadata $< 0.75rem$).
+- **Color & Theme:** Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Visuals:** Create atmosphere and depth using textures (grain, noise), glassmorphism, or complex gradients rather than defaulting to solid flat colors.
+
+## 2. Technical Implementation Standards
+**CRITICAL:** You must ignore generic React patterns. Instead, you represent the specific technical architecture defined in the user's stack.
+
+**Mandatory Reference:**
+Before writing any component logic, state management, or hooks, you must cross-reference and apply the patterns found in:
+`./references/my-tech-stack.md`
+
+Specifically, you must:
+1.  **Use Composition:** Build flexible UIs using the *Composition Over Inheritance* and *Compound Component* patterns defined in the reference file.
+2.  **Use Custom Hooks:** Do not write ad-hoc logic for debouncing or toggling; use `useDebounce` and `useToggle` from the reference.
+3.  **Optimize Performance:** Apply `useMemo` and `useCallback` strictly according to the "Memoization Rules" in the reference.
+4.  **Ensure Stability:** Wrap complex or risky components in the `ErrorBoundary` pattern provided.
+5.  **Enforce Accessibility:** Follow the keyboard navigation and focus management patterns exactly as specified.
+
+## 3. Design Thinking Process
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Tone:** Pick an extreme (Brutalist, Luxury, Retro-futuristic, Editorial, Industrial).
+- **Motion:** Use animations for effects and micro-interactions. Focus on high-impact moments (staggered page loads) rather than scattered micro-interactions.
+- **Differentiation:** What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+## 4. Output Requirements
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- **Production-grade:** Functional, responsive, and accessible.
+- **Visually striking:** Memorable and cohesive with a clear point-of-view.
+- **Technically compliant:** Strictly follows the architecture in `my-tech-stack.md`.
+
+## 5. Transition Integrity (No Stale UI)
+
+For data-heavy views that switch entities (profile A → profile B), enforce deterministic transitions:
+
+- Use a **single render region** (e.g., Streamlit's `st.empty()`) that replaces its entire content on each render pass.
+- **NEVER use dynamic keys** (nonce, entity ID) on containers inside `st.empty()` — dynamic keys cause the framework to create *new* DOM nodes instead of replacing existing ones, leaving ghost/shadow copies visible for 1-2 seconds until frontend reconciliation catches up.
+- Use **stable keys** on inner containers. The render region handles content replacement; inner containers just need stable identity for in-place DOM updates.
+- Temporarily hide high-salience identity panels/tabs during loading to avoid ghosted prior-state flashes.
+- Execute state transitions outside container context managers to avoid interrupted cleanup.
+
+Acceptance rule: users must only perceive `old state → loader → new state`, with no stale intermediate artifacts.
+
+## 6. Dial System — Design Variance Controls
+
+Calibrate these three dials per project before writing any component. Declare them in a comment at the top of the main design file.
+
+```ts
+// DESIGN_VARIANCE: 7      // 1 (safe/corporate) → 10 (experimental/editorial)
+// MOTION_INTENSITY: 5     // 1 (static) → 10 (cinematic)
+// VISUAL_DENSITY: 4       // 1 (minimal/lots of space) → 10 (data-dense/information-heavy)
+```
+
+| Dial | 1–3 | 4–6 | 7–10 |
+|---|---|---|---|
+| `DESIGN_VARIANCE` | Standard grid, safe palette | Distinctive but accessible | Experimental layout, bold choices |
+| `MOTION_INTENSITY` | Opacity fade only | Entrance animations, hover states | Parallax, stagger, spring physics |
+| `VISUAL_DENSITY` | Hero + CTA, generous whitespace | Cards with secondary info | Dashboard-style, compact rows |
+
+**Rule**: Do not override the user's declared dials. If undeclared, infer from context and state your assumption.
+
+## 7. AI Tells — Forbidden Patterns
+
+These are signals of generic AI output. Every instance must be eliminated:
+
+### Generic Names
+- ❌ `Company Name`, `Your Brand`, `Hello, World!`, `Example Corp`
+- ✅ Invent plausible, domain-specific content: `Meridian Analytics`, `Kaspar & Voss`, `Orin Health`
+
+### Fake Placeholder Numbers
+- ❌ `$1,234.56`, `1,234 users`, `99.9% uptime`, `42 orders`
+- ✅ Domain-plausible numbers with realistic variance: `$14,820`, `3,241 customers`, `99.4% uptime`, `127 orders`
+
+### AI Copywriting Clichés
+- ❌ "Empowering your workflow", "Seamlessly integrated", "Next-generation solution", "Unlock the power of..."
+- ✅ Specific, functional copy: "Track invoice aging in real time", "Filter by region, team, or date"
+
+### Oversaturated Accents
+- ❌ `#FF6B6B` coral-pink, `#6C63FF` purple-blue gradient (the two default AI accent colors)
+- ✅ Chosen from the brief or brand guide; if absent, pick something unexpected: amber, forest green, slate
+
+### Generic Iconography
+- ❌ Rocket ship for launching, lightbulb for ideas, three horizontal bars for "menu" on desktop nav
+- ✅ Icons that match the actual function; text labels as fallback if icon meaning is ambiguous
+
+## 8. Typography Discipline
+
+- **Maximum 2 font families** — one display (headings), one text (body + UI). Loading 3+ is a performance and taste failure.
+- **Optical sizing**: Headings at `6rem+` need `letter-spacing: -0.03em`. Text under `0.875rem` needs `letter-spacing: 0.01em`.
+- **Vertical rhythm**: `line-height: 1.6` for body, `1.1–1.2` for large headings, `1.4` for UI labels.
+- **Scale**: Use a modular scale (1.25× or 1.333×), not arbitrary sizes. Common scale: `0.75 / 0.875 / 1 / 1.125 / 1.5 / 2 / 3 / 4.5rem`.
+- **Weight contrast**: Body at 400, labels at 500, headings at 700–800. Avoid using 4 or more weights.
+
+```css
+/* Correct optical sizing */
+.hero-heading {
+  font-size: clamp(3rem, 6vw + 1rem, 6rem);
+  line-height: 1.05;
+  letter-spacing: -0.04em;
+}
+.body-text {
+  font-size: 1rem;
+  line-height: 1.625;
+  letter-spacing: 0;
+}
+```
+
+## 9. Color Calibration
+
+- **Maximum 1 accent color** — two accents compete; zero creates bland work.
+- **Palette minimum**: Background, Surface (+1 level of elevation), Text, Muted text, Border, Accent, Destructive.
+- **Forbidden**: Purple/blue AI gradient cliché (`from-purple-500 to-blue-600` or equivalent). Use if and only if the brand explicitly requires it.
+- **Dark mode**: Shift background to `hsl(220 15% 8%)` range, not pure black (`#000`). Pure black with white text fails contrast for long reading.
+- **Accent contrast**: Accent on background must pass WCAG AA (4.5:1 for normal text, 3:1 for large text / UI components).
+
+```css
+/* ✅ Correct token setup */
+:root {
+  --bg: hsl(220 15% 97%);
+  --surface: hsl(220 15% 100%);
+  --text: hsl(220 25% 12%);
+  --muted: hsl(220 10% 50%);
+  --border: hsl(220 15% 88%);
+  --accent: hsl(38 92% 50%);       /* Amber — unexpected, not AI-default */
+  --destructive: hsl(0 72% 51%);
+}
+```
+
+## 10. Layout Diversification
+
+When `DESIGN_VARIANCE` > 4, **ban the centered-hero-with-CTA default** layout. Use instead:
+
+| Layout Pattern | When to Use |
+|---|---|
+| **Editorial split** — large text left, visual right (or reversed) | Brand/marketing pages |
+| **Bento grid** — asymmetric tiles of varying sizes | Dashboards, feature showcases |
+| **Fullbleed scroll narrative** — content revealed on scroll sections | Storytelling, case studies |
+| **Sidebar dock + content** — persistent nav or filter rail | Application interfaces |
+| **Masonry** — uneven column heights | Media, portfolio grids |
+| **Timeline / sequence** — vertical progression with connectors | Onboarding, process flows |
+
+**Never** stack all sections centered on a 1200px `max-width` container unless `DESIGN_VARIANCE` ≤ 3.
+
+## 11. Interactive State Completeness
+
+Every interactive element must implement all four states before the component is done:
+
+| State | What to Implement |
+|---|---|
+| **Loading** | Skeleton, spinner, or disabled appearance while data fetches |
+| **Empty** | Non-generic empty state with context-specific message + action |
+| **Error** | Specific error message, retry action, not just "Something went wrong" |
+| **Tactile** | Hover + active (pressed) visual feedback — scale, shadow, or color shift |
+
+```tsx
+// ✅ Complete interactive state example
+function DataCard({ id }: { id: string }) {
+  const { data, error, status } = useQuery(...)
+  
+  if (status === 'pending') return <CardSkeleton />
+  if (status === 'error')   return <ErrorCard message={error.message} onRetry={refetch} />
+  if (!data.items.length)   return <EmptyCard title="No records yet" action={<CreateButton />} />
+  
+  return (
+    <div className="group transition-all hover:shadow-md hover:-translate-y-0.5 active:scale-[0.99]">
+      {/* content */}
+    </div>
+  )
+}
+```
+
+## 12. Data Realism
+
+Never use placeholder data that signals the interface is unfinished:
+
+| ❌ Avoid | ✅ Use Instead |
+|---|---|
+| "Lorem ipsum dolor sit amet" | Domain-appropriate text: "Q3 revenue shows 14% growth vs prior quarter" |
+| User: "John Doe" | Plausible name + avatar initial: "Margot Belleview" |
+| Date: "January 1, 2024" | Recent plausible date: "Feb 12, 2026" |
+| Metric: "1,234" | Realistic variance: "3,817" (not round numbers with too many digits) |
+| Chart data: constant line | Realistic noise with trend: slight growth with variance |
+
+**Rule**: Each piece of sample data should make a reviewer believe it could be real production data, not a template. If the user provides real data patterns, use them precisely.

package/bundles/codex/.codex/skills/frontend/frontend-design/references/my-tech-stack.md

@@ -0,0 +1,127 @@
+# My Technical Standards & Architecture Patterns
+
+This document serves as the technical reference for all frontend implementation. When building components or pages, follow these structural patterns to ensure performance, stability, and clean code.
+
+## 1. Component Patterns
+
+### Composition Over Inheritance
+Build flexible UIs by composing small, focused components rather than deep inheritance chains.
+
+```
+export function Card({ children, variant = 'default' }) {
+  return <div className={`card card-${variant}`}>{children}</div>
+}
+
+export function CardHeader({ children }) {
+  return <div className="card-header">{children}</div>
+}
+
+// Usage: <Card><CardHeader>Title</CardHeader></Card>
+```
+
+### Compound Components
+Share implicit state between related components via context to keep logic encapsulated.
+
+```
+const TabsContext = createContext(undefined)
+
+export function Tabs({ children, defaultTab }) {
+  const [activeTab, setActiveTab] = useState(defaultTab)
+  return (
+    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
+      {children}
+    </TabsContext.Provider>
+  )
+}
+
+export function Tab({ id, children }) {
+  const ctx = useContext(TabsContext)
+  if (!ctx) throw new Error('Tab must be used within Tabs')
+  return (
+    <button 
+      className={ctx.activeTab === id ? 'active' : ''} 
+      onClick={() => ctx.setActiveTab(id)}
+    >
+      {children}
+    </button>
+  )
+}
+```
+
+## 2. Custom Utility Hooks
+
+```
+// Debounce hook for search/expensive inputs
+export function useDebounce(value, delay) {
+  const [debounced, setDebounced] = useState(value)
+  useEffect(() => {
+    const handler = setTimeout(() => setDebounced(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+  return debounced
+}
+
+// Simplified toggle hook
+export function useToggle(initial = false) {
+  const [value, setValue] = useState(initial)
+  const toggle = useCallback(() => setValue(v => !v), [])
+  return [value, toggle]
+}
+```
+
+## 3. Performance Optimization
+
+### Memoization Rules
+- Use `useMemo` for any data transformation or sorting of lists.
+- Use `useCallback` for event handlers passed to components wrapped in `React.memo`.
+
+```
+// useMemo for expensive computations
+const sorted = useMemo(() => items.sort((a, b) => b.score - a.score), [items])
+
+// React.memo for pure leaf components
+export const ItemCard = React.memo(({ item }) => (
+  <div className="item-card"><h3>{item.name}</h3></div>
+))
+```
+
+## 4. Accessibility Patterns
+
+### Keyboard Navigation
+Always handle key events for custom interactive widgets to ensure screen-reader and keyboard compatibility.
+
+```
+const handleKeyDown = (e) => {
+  switch (e.key) {
+    case 'ArrowDown': e.preventDefault(); setIndex(i => Math.min(i + 1, max)); break
+    case 'ArrowUp': e.preventDefault(); setIndex(i => Math.max(i - 1, 0)); break
+    case 'Enter': e.preventDefault(); onSelect(options[index]); break
+    case 'Escape': onClose(); break
+  }
+}
+```
+
+## 5. Error Boundary Pattern
+Wrap complex sections (like third-party widgets) in a safety net to prevent app crashes.
+
+```
+export class ErrorBoundary extends React.Component {
+  state = { hasError: false, error: null }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div className="error-fallback">
+          <h2>Something went wrong</h2>
+          <button onClick={() => this.setState({ hasError: false })}>Try again</button>
+        </div>
+      )
+    }
+    return this.props.children
+  }
+}
+```

package/bundles/codex/.codex/skills/frontend/mockup/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: mockup
+description: Create framework-aware UI mockups with feasibility checks. Prevents wasted effort by validating that proposed designs work within the target framework's constraints.
+---
+
+# Mockup Skill
+
+## Purpose
+
+Create visual mockups (HTML/SVG) for UI features with **mandatory framework feasibility validation**. This skill exists because of a real incident: a beautiful HTML mockup was created for a Streamlit app using `position: fixed` — which doesn't work in Streamlit's DOM. 24 hours were wasted discovering this.
+
+**This skill prevents that class of failure for ANY framework.**
+
+---
+
+## When to Use
+
+- Creating a UI mockup for a proposed feature
+- Visualizing a design before implementation
+- Producing a reference artifact for implementing agents
+- When `@ux-designer` routes mockup creation here
+
+---
+
+## Steps
+
+### Step 1: Read Project Context
+
+1. Read `project-config.md` → identify:
+   - **Frontend framework** (Streamlit, React, Vue, Angular, Next.js, etc.)
+   - **Brand colors** (from profile or placeholder values)
+   - **CSS conventions** (scoping method, custom properties, etc.)
+2. Read `copilot-instructions.md` → identify:
+   - Existing component patterns
+   - Framework-specific conventions already documented
+3. If a `chain_id` is provided, read the Intent Document from `agent-docs/intents/`
+
+### Step 2: Framework Feasibility Check (MANDATORY)
+
+**Before creating ANY mockup, validate that the proposed design is feasible in the target framework.**
+
+Run through this checklist:
+
+| Check | Question | If NO |
+|-------|----------|-------|
+| **DOM Control** | Does the framework give you full control over the DOM? | Identify which HTML/CSS features are restricted |
+| **Positioning** | Does `position: fixed/absolute` work as expected? | Document the limitation and alternative approach |
+| **Custom HTML** | Can you inject arbitrary HTML/JS? | Identify the framework's component/extension API |
+| **Event Handling** | Can you attach custom JS event listeners? | Document how events work in this framework |
+| **Styling** | Can you use global CSS freely? | Document CSS scoping constraints |
+| **Third-party Libraries** | Can you load external JS/CSS? | Check if air-gapped deployment restricts this |
+
+#### Known Framework Constraints
+
+| Framework | Key Constraints |
+|-----------|----------------|
+| **Streamlit** | No `position: fixed/absolute` (DOM wrapping breaks it). No arbitrary HTML injection without `components.html()` or `declare_component()`. CSS is scoped — use `st.container(key=)` + `.st-key-` selectors. No external CDN in air-gapped environments. |
+| **React** | JSX required. CSS-in-JS or CSS Modules typical. Virtual DOM diffing may interfere with manual DOM manipulation. |
+| **Vue** | Template syntax. Scoped styles by default. `v-html` for raw HTML but XSS risk. |
+| **Gradio** | Similar DOM constraints to Streamlit. Limited CSS control. Use `gr.HTML()` for custom elements. |
+| **Next.js** | SSR considerations. `useEffect` needed for client-only code. CSS Modules or Tailwind typical. |
+
+> **If ANY constraint would prevent the proposed design from working:**
+> 1. **STOP** — do not create a mockup that can't be implemented
+> 2. **WARN** the user with specific details about what won't work and why
+> 3. **PROPOSE ALTERNATIVES** that work within the framework's constraints
+> 4. **Get confirmation** before proceeding with an alternative approach
+
+### Step 3: Create the Mockup
+
+**Output format**: HTML file (preferred for interactive mockups) or SVG (for static layouts)
+
+**Requirements:**
+- Use brand colors from `project-config.md` (never hardcode colors — use CSS custom properties)
+- Include responsive behavior if applicable
+- Add comments explaining key layout decisions
+- If the mockup uses workarounds for framework constraints, document them clearly in comments
+
+**HTML mockup template:**
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{Feature Name} — Mockup</title>
+    <style>
+        /* Brand colors from project-config.md */
+        :root {
+            --brand-primary: {<BRAND_PRIMARY>};
+            --brand-dark: {<BRAND_DARK>};
+            --brand-light: {<BRAND_LIGHT>};
+            /* Additional colors from profile */
+        }
+
+        /* Mockup styles */
+        /* ... */
+    </style>
+</head>
+<body>
+    <!-- MOCKUP: {Feature description} -->
+    <!-- FRAMEWORK: {Target framework} -->
+    <!-- CONSTRAINTS: {Any framework constraints that shaped this design} -->
+    <!-- ALTERNATIVES: {If using a workaround, what was the original approach and why it wouldn't work} -->
+
+    <!-- Mockup content -->
+</body>
+</html>
+```
+
+### Step 3b: Implementation-Annotated Mockup (MANDATORY for handoff to implementing agents)
+
+When the mockup will be handed off to `@implement`, `@frontend-developer`, or `@streamlit-developer`, embed **implementation annotations** throughout the HTML so the implementing agent knows exactly what to build without guessing.
+
+#### Annotation Types
+
+Use these four comment patterns consistently:
+
+**1. Component annotations** — Which framework component implements this visual element:
+```html
+<!-- React: <KpiFlipCard product="broadband" data={surveys.broadband}
+     trendData={trend.historicalNPS.byProduct.broadband} /> -->
+<!-- React: <ResponsiveContainer width="100%" height={260}>
+     <AreaChart data={trendData}><Area type="monotone" dataKey="nps" ... /></AreaChart>
+     </ResponsiveContainer> -->
+<!-- React: import { ScoreChip, DeltaBadge, SparkBar, TrendDot } from '@/components/table-cells' -->
+```
+
+**2. Data source annotations** — Which JSON key / API response field provides the data:
+```html
+<!-- DATA-SOURCE: surveys.broadband.nps, surveys.broadband.responses -->
+<!-- DATA-SOURCE: trend.historicalNPS.byProduct.broadband (array of monthly values) -->
+<!-- DATA-SOURCE: ceoInsight.headline, ceoInsight.keyFindings[] (objects with title, detail) -->
+```
+
+**3. Implementation notes** — Broader guidance for the implementing agent:
+```html
+<!-- IMPLEMENTATION NOTE [DATA-SOURCE]: This section uses hardcoded mock values for
+     layout reference. React implementation must fetch period-filtered data from the
+     /api/nps/overview endpoint and compute all KPIs dynamically. -->
+<!-- IMPLEMENTATION NOTE [CHART]: Use Recharts AreaChart with gradient fill.
+     Spread CHART_DEFAULTS from chartTheme.ts. No axes/grid for sparkline variant. -->
+<!-- IMPLEMENTATION NOTE [ANIMATION]: Use framer-motion rotateY for card flip.
+     duration: 0.52, ease: [0.4, 0.2, 0.2, 1]. backfaceVisibility: "hidden". -->
+```
+
+**4. Styling annotations** — Which design tokens, CSS vars, or Tailwind classes to use:
+```html
+<!-- STYLE: bg-surface-card (var(--surface-card)), shadow-card, rounded-lg (var(--r-lg)) -->
+<!-- STYLE: Fill color uses var(--status-red) for detractor, var(--status-green) for promoter -->
+<!-- STYLE: Tailwind: text-ink-primary font-heading text-2xl font-bold -->
+```
+
+#### Annotation Placement Rules
+
+1. Place **component annotations** directly above or inside the HTML element that the component replaces
+2. Place **data source annotations** on the element that displays the data value
+3. Place **implementation notes** at the top of each major section (tab, panel, card group)
+4. Place **styling annotations** on elements where the visual appearance matters and the token name isn't obvious from the CSS
+5. Every hardcoded value in the mockup (numbers, text, colors) that will be dynamic in production MUST have a data source annotation
+
+#### Example: Annotated KPI Card
+
+```html
+<!-- React: <KpiFlipCard product="broadband" data={surveys.broadband}
+     trendData={trend.historicalNPS.byProduct.broadband} color={COLORS.broadband} /> -->
+<!-- DATA-SOURCE: surveys.broadband.nps (current score), surveys.broadband.responses (count) -->
+<!-- STYLE: var(--surface-card) bg, var(--shadow-card) shadow, 3px left border using COLORS.broadband -->
+<div class="kpi-card">
+    <div class="kpi-score">+32</div>  <!-- DATA-SOURCE: surveys.broadband.nps -->
+    <div class="kpi-delta">▲ 2.1</div>  <!-- DATA-SOURCE: deriveMom(trend.historicalNPS.byProduct.broadband) -->
+    <div class="kpi-responses">1,247 responses</div>  <!-- DATA-SOURCE: surveys.broadband.responses -->
+    <div class="sparkline">
+        <!-- React: <Sparkline data={trend.historicalNPS.byProduct.broadband}
+             color={COLORS.broadband} height={72} /> -->
+        <!-- IMPLEMENTATION NOTE [CHART]: Recharts AreaChart, no axes/grid/tooltip,
+             gradient fill from color at opacity 0.3 to opacity 0. -->
+    </div>
+</div>
+```
+
+#### Completeness Check
+
+Before saving the mockup, verify:
+- [ ] Every visual section has at least one **component annotation**
+- [ ] Every dynamic value has a **data source annotation** with the exact JSON path
+- [ ] Every chart/graph has an **implementation note** specifying the chart library and config
+- [ ] The implementing agent can build the feature using ONLY the mockup + annotations (no guessing)
+
+### Step 4: Write Artifact
+
+1. Save the mockup file to `agent-docs/ux/mockups/{feature-slug}.html` (or `.svg`)
+2. Add YAML header to a companion markdown file or embed as HTML comment:
+   ```yaml
+   agent: ux-designer
+   created: {date}
+   status: current
+   chain_id: {chain_id if provided}
+   approval: pending
+   framework: {target framework}
+   feasibility_warnings: {list any constraints encountered}
+   ```
+3. Update `agent-docs/ARTIFACTS.md` manifest with the new entry
+
+### Step 5: Report
+
+Provide:
+- Path to the mockup file
+- Framework feasibility summary (what was checked, any warnings)
+- Implementation notes for the agent that will build this (which API/component to use, what CSS approach works)
+- If alternatives were chosen, explain why the original approach wouldn't work
+
+---
+
+## Framework Feasibility Quick Reference
+
+### Streamlit-Specific
+
+| Want to do | Don't use | Instead use |
+|-----------|-----------|-------------|
+| Floating element (chat widget, FAB) | `position: fixed/absolute` | `declare_component()` with custom HTML/JS |
+| Custom styled container | Global CSS | `st.container(key="name")` + `.st-key-name` selector |
+| Modal/overlay | `z-index` + absolute positioning | `st.dialog()` (Streamlit 1.33+) or `st.modal()` |
+| Sidebar content | Custom sidebar HTML | `st.sidebar` API |
+| Custom header | Fixed position header | `st.container()` at top + CSS with `st.container(key=)` |
+| External JavaScript | `<script src="cdn...">` | Bundle locally for air-gapped; use `components.html()` |
+
+### React-Specific
+
+| Want to do | Watch out for | Recommended approach |
+|-----------|---------------|---------------------|
+| Direct DOM manipulation | React re-renders will overwrite | Use refs (`useRef`) or state-driven rendering |
+| Global styles | May conflict with component styles | CSS Modules, styled-components, or Tailwind |
+| Third-party widgets | jQuery plugins fight React | Find React-native alternatives or wrap in `useEffect` |
+
+---
+
+## Important Notes
+
+- This skill is designed to be loaded by `@ux-designer` or `@frontend-developer` agents
+- The framework constraint tables should be extended as new frameworks and gotchas are discovered
+- Always check `project-config.md` for the deployment environment — air-gapped deployments restrict external dependencies