@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/enterprise-dashboard-aesthetic-system/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: enterprise-dashboard-aesthetic-system
+description: "Use when: upgrading React/Vite enterprise dashboards, harmonizing dashboard pages, improving executive analytics UI aesthetics, creating cohesive dashboard design systems, adding tasteful motion, or turning data-heavy pages into a polished narrative cockpit. Applies to RevSight-style FastAPI + React + Tailwind + shadcn dashboards."
+---
+
+# Enterprise Dashboard Aesthetic System
+
+Use this skill to turn a functional data dashboard into a cohesive executive analytics product. The goal is not decoration. The goal is a calm, high-trust cockpit where every page feels like part of the same operational story.
+
+## Outcome Standard
+
+Ship a dashboard that feels:
+
+- Cohesive across every route, not page-by-page styled.
+- Rich enough to attract attention, restrained enough for repeated work.
+- Data-first: charts, tables, KPIs, maps, and filters remain readable.
+- Brand-aware: brand color drives interaction; semantic colors drive data.
+- Accessible: keyboard focus, contrast, reduced motion, and touch targets survive the polish pass.
+
+## Design Direction
+
+Use this default direction for telecom, finance, operations, and internal enterprise dashboards:
+
+- **Aesthetic:** warm executive cockpit with machined surfaces, fine-line grids, and quiet depth.
+- **Brand accent:** one interaction accent, usually the brand color.
+- **Data palette:** keep separate semantic colors for chart streams and status states.
+- **Typography:** one readable UI family, one condensed/display family for KPI punch, one tabular numeric family.
+- **Motion:** page and card entrance via transform + opacity only; no layout animation.
+
+Avoid marketing-page hero layouts, decorative blobs, generic blue-purple gradients, and oversized copy that pushes the actual data below the fold.
+
+## Workflow
+
+1. **Map the shared layer first**
+   - Find the app shell, global stylesheet, theme store, Tailwind config, shadcn primitives, and route pages.
+   - Prefer global tokens and shared classes over one-off page styles.
+   - Identify token gaps such as undefined `--surface-*`, status colors, chart colors, or duplicate font definitions.
+
+2. **Establish a token contract**
+   - Define primitive, semantic, and component tokens in CSS custom properties.
+   - Include light and dark variants together.
+   - Include aliases for common usage: `--bg`, `--surface`, `--surface-1`, `--surface-2`, `--border-soft`, `--ink-1..4`, `--brand`, `--brand-tint`, `--green`, `--amber`, `--red`, `--blue`, chart colors, radius, shadows, and motion curve.
+   - Point Tailwind `fontFamily` and shadcn HSL bridge tokens at the same source of truth.
+
+3. **Separate interaction color from data color**
+   - Brand color: nav active states, primary actions, focus rings, selected chips, important app affordances.
+   - Blue/green/amber/red: charts, quality status, revenue signals, health, warnings, and semantic data states.
+   - Do not let every page become one hue. Each page can lead with a different data semantic while sharing brand interaction rules.
+   - User-selectable color themes must go deeper than accents. Override semantic background, surface, border, ink, shadow, chart, and map-marker tokens so the selected palette changes the whole workspace.
+   - Keep product identity separate from theme identity. App names, official logos, and fixed brand marks should use dedicated `--app-*` tokens instead of dynamic `--brand` tokens.
+
+4. **Create page storytelling grammar**
+   - Every major route should have a hero/story section with:
+     - a short eyebrow naming the operational lens,
+     - an H1 that explains the decision surface,
+     - concise supporting copy,
+     - fact pills grounded in the active data window/source,
+     - an optional signal card summarizing the page's core story.
+   - Utility pages such as detail browsers still need a hero. They should feel like investigative workspaces, not leftover forms.
+
+5. **Upgrade shared surfaces**
+   - Panels/cards use warm gradients, subtle borders, inset highlights, and a consistent shadow scale.
+   - KPI cards use top accent bars and tabular numbers.
+   - Tables use readable sticky-like headers, clear hover state, and tabular numeric columns.
+   - Chart frames use a quiet inset surface so charts feel intentionally housed.
+   - Maps use a contained frame with matching radius, border, and attribution styling.
+
+6. **Motion and interaction rules**
+   - Animate only `transform` and `opacity`.
+   - Use one custom curve, for example `cubic-bezier(0.32, 0.72, 0, 1)`.
+   - Add staggered page-section entrance sparingly.
+   - Respect `prefers-reduced-motion` by disabling entrance animation and shortening transitions.
+   - Buttons and cards should have hover and active states. Keyboard focus must remain visible.
+
+7. **Mobile and dense-data safeguards**
+   - Collapse asymmetric layouts to one column below tablet width.
+   - Keep main controls near or above 40-44px on mobile.
+   - Avoid horizontal page overflow; tables may scroll inside their own container.
+   - Do not hide core data just to preserve a desktop composition.
+
+8. **Verification**
+   - Run TypeScript build and lint where available.
+   - Check modified files for diagnostics.
+   - Use the browser at desktop and mobile widths to verify no overlap, no blank charts/maps, and no unreadable text.
+   - Review light and dark modes if the app supports both.
+
+## RevSight Implementation Notes
+
+For RevSight-style apps, start with these files:
+
+- `frontend/src/styles/globals.css` for tokens, shared surfaces, motion, tables, charts, maps, and responsive rules.
+- `frontend/tailwind.config.js` for token-backed font utilities.
+- `frontend/src/components/layout/AppShell.tsx` for sidebar, topbar, navigation, and source-card story details.
+- `frontend/src/components/ui/` for shadcn primitive defaults.
+- `frontend/src/pages/*Page.tsx` for route-specific hero copy and signal cards.
+- `frontend/src/stores/themeStore.ts` and `frontend/src/lib/colorTheme.ts` for persisted color themes, Settings theme options, and map/chart palette wiring.
+
+Useful route grammar:
+
+- Roaming: footprint and country-level operating pulse.
+- Geo: spatial spend density and country/operator map context.
+- Cost/Revenue: revenue yield, leakage watch, service mix.
+- CDR Detail: forensic row-level traceability and export workflow.
+- Data Quality: trust, risk, and data integrity verdicts.
+- Observability: runtime health and usage signals.
+- Settings: control center for appearance, data, telemetry, cache, and deployment health.
+
+## Quality Checklist
+
+- [ ] Brand accent is consistent across nav, focus, chips, and primary actions.
+- [ ] App name/logo colors remain stable when user-selectable themes change.
+- [ ] Theme palettes affect surfaces, ink, borders, shadows, charts, and maps, not just accents.
+- [ ] Data colors are semantic and not overloaded as interaction colors.
+- [ ] All route heroes follow the same storytelling grammar.
+- [ ] Cards, panels, tables, chart frames, map frames, controls, and badges share tokenized surfaces.
+- [ ] No undefined CSS variables are used.
+- [ ] No negative letter spacing or viewport-scaled font sizing is introduced.
+- [ ] Motion respects reduced-motion preferences.
+- [ ] Mobile layout collapses cleanly without text overlap or clipped controls.
+- [ ] Build, lint, and browser smoke checks pass.

package/bundles/antigravity-plugin-extras/skills/excalidraw/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: excalidraw
+context: fork
+description: "Brand-themed Excalidraw diagrams for project documentation"
+---
+
+# Excalidraw Diagram Generation
+
+Generate `.excalidraw` JSON files for architecture, flowcharts, and whiteboard-style diagrams using consistent brand theming.
+
+> **Project Context** — Read `project-config.md` in the repo root for brand tokens, color palette, and project metadata.
+
+Use these colors for diagrams that appear in project docs, runbooks, or architecture artifacts.
+
+## When to Use
+
+- Creating architecture or system design diagrams for systems
+- Drawing flowcharts or decision trees for internal processes
+- Building mind maps or relationship diagrams with brand theming
+- Producing whiteboard visuals for project documentation
+
+## Supported Diagram Types
+
+| Type           | Use Case                              |
+|----------------|---------------------------------------|
+| Flowchart      | Processes, decision trees             |
+| Architecture   | System components, microservices      |
+| Mind Map       | Concept hierarchies, brainstorming    |
+| Relationship   | Entity relationships, data models     |
+| Sequence       | Message flows, interactions           |
+
+## Phase 1: Plan Layout
+
+### Spacing
+
+| Context                     | Pixels  |
+|-----------------------------|---------|
+| Horizontal gap              | 200-300 |
+| Vertical gap                | 100-150 |
+| Canvas margin               | 50+     |
+| Arrow clearance             | 20-30   |
+
+### Brand Color Palette
+
+| Role            | Hex        | Use |
+|-----------------|------------|-----|
+| Primary entity  | `#E10A0A`  | Primary Red — main components, CTAs |
+| Process step    | `#ECFDF5`  | Light green fill (border #10B981) |
+| Key / central   | `#FEF3C7`  | Light yellow (border #F59E0B) |
+| Warning / error | `#FFF7ED`  | Light orange (border #F97316) |
+| Background      | `#F8F9FA`  | Light background |
+| Default stroke  | `#1F2937`  | Navy |
+
+Keep total elements under 20 per diagram. Split larger systems.
+
+## Phase 2: JSON Structure
+
+Same as standard Excalidraw: `type`, `version`, `source`, `elements`, `appState`, `files`. Use brand palette hex values in `backgroundColor` and `strokeColor`.
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "https://excalidraw.com",
+  "elements": [],
+  "appState": {
+    "viewBackgroundColor": "#F8F9FA",
+    "gridSize": 20
+  },
+  "files": {}
+}
+```
+
+## Phase 3: Element Types
+
+Use rectangle, diamond, ellipse, arrow, and text. Apply brand colors from the table above.
+
+### Rectangle (boxes, containers)
+
+```json
+{
+  "id": "step-1", "type": "rectangle",
+  "x": 100, "y": 100, "width": 200, "height": 80,
+  "strokeColor": "#1F2937", "backgroundColor": "#ECFDF5",
+  "fillStyle": "solid", "strokeWidth": 2, "roughness": 1,
+  "opacity": 100, "roundness": { "type": 3 },
+  "isDeleted": false, "locked": false
+}
+```
+
+### Diamond (decisions)
+
+```json
+{ "id": "d1", "type": "diamond", "x": 200, "y": 100,
+  "width": 140, "height": 140, "strokeColor": "#1F2937",
+  "backgroundColor": "#FEF3C7" }
+```
+
+### Ellipse (start/end, states)
+
+```json
+{ "id": "start", "type": "ellipse", "x": 100, "y": 100,
+  "width": 120, "height": 80, "strokeColor": "#1F2937",
+  "backgroundColor": "#ECFDF5" }
+```
+
+### Arrow (connections)
+
+```json
+{
+  "id": "a1", "type": "arrow",
+  "x": 300, "y": 140, "width": 100, "height": 0,
+  "points": [[0, 0], [100, 0]],
+  "roundness": { "type": 2 },
+  "strokeColor": "#1F2937",
+  "startBinding": null, "endBinding": null
+}
+```
+
+Directions: horizontal `[[0,0],[200,0]]`, vertical `[[0,0],[0,150]]`, diagonal `[[0,0],[200,150]]`.
+
+**Arrow connections (mandatory):** Arrows that should attach to shapes must either **(A)** use `startBinding` and `endBinding` with `elementId` (and optional `focus`, `gap`) pointing at the source and target elements, or **(B)** be drawn so the arrow's start/end coordinates sit on the edges of the source and target shapes. Unbound arrows must run from source to target; direction and length must match the intended flow. See `references/reliable-diagrams.md` for binding structure and example.
+
+### Text (labels, titles)
+
+```json
+{
+  "id": "t1", "type": "text",
+  "x": 100, "y": 50, "width": 300, "height": 36,
+  "text": "System Architecture", "fontSize": 28,
+  "fontFamily": 5, "textAlign": "center",
+  "strokeColor": "#1F2937"
+}
+```
+
+**Fonts (mandatory):** Use **Excalifont** as the default for all text (do not use Virgil). In JSON set `fontFamily`: **`5`** for Excalifont. Optionally, when your Excalidraw version or font picker supports them: use **Comic Shanns** for headings (e.g. diagram title, section labels); **Lilita One** for emphasis or important callouts; **Nunito** for legends and descriptive text. If a font is not available, fall back to Excalifont.
+
+**Text sizing (mandatory):** For every `type: "text"` element, set `width` to at least **max(line length) × fontSize × 0.7 + 16px** and `height` to at least **fontSize × 1.2 × number of lines × 1.1**. This matches `references/reliable-diagrams.md` and adds horizontal and vertical padding so labels never clip. Never use a fixed small width for variable-length content — Excalidraw clips text to the element bounds.
+
+**Text inside shapes:** Some Excalidraw versions do not render the `text` property when it is embedded on rectangle, ellipse, or diamond elements. For reliable labels, use **separate `type: "text"` elements** positioned inside the shape, with width/height sized as above. Include `originalText` and `lineHeight`: 1.25 on text elements for compatibility.
+
+## Phase 4: Common Patterns
+
+### Connected Boxes
+
+Use bindings so arrows attach to boxes. Example: two rectangles with one arrow using `startBinding` and `endBinding`; see `templates/reliable-flowchart.excalidraw`.
+
+### Decision Branch
+
+Place a diamond, then arrows for each branch. **Each arrow must point toward the element that branch leads to**; place the label (e.g. YES, NO) next to the correct arrow. If using bindings, set `endBinding.elementId` to the target shape.
+
+### Mind Map (Radial)
+
+```
+angle = (2 * PI * index) / branchCount
+x = centerX + radius * cos(angle)
+y = centerY + radius * sin(angle)
+```
+
+## Phase 5: Save and Open
+
+Save as `<name>.excalidraw`. Open in excalidraw.com, VS Code Excalidraw extension, or Obsidian.
+
+### Validation Checklist
+
+- [ ] All IDs unique
+- [ ] No overlapping elements
+- [ ] Text readable (fontSize 16+); text elements have width/height sized so content is not clipped (see references/reliable-diagrams.md)
+- [ ] Arrows connect logically: use bindings or draw arrows from source edge to target edge; direction matches flow
+- [ ] Decision branches: each arrow points toward the correct target element
+- [ ] Brand color scheme applied
+- [ ] Valid JSON
+- [ ] Under 20 total elements
+
+## Quick Reference
+
+| Element   | Type        | Key Properties                          |
+|-----------|-------------|------------------------------------------|
+| Box       | `rectangle` | x, y, width, height, backgroundColor    |
+| Circle    | `ellipse`   | x, y, width, height                     |
+| Decision  | `diamond`   | x, y, width (= height)                  |
+| Arrow     | `arrow`     | x, y, points, startBinding, endBinding  |
+| Label     | `text`      | x, y, text, fontSize, fontFamily (5 = Excalifont), width, height |
+
+## Resources
+
+All paths below are **within this skill** (self-contained). Do not reference generic or media Excalidraw assets.
+
+- **Reliable diagrams (text sizing, arrow bindings):** see `references/reliable-diagrams.md`. Required for architecture, flowcharts, network, and ER diagrams.
+- **Full element types and schema:** see `references/element-types.md` and `references/excalidraw-schema.md`.
+- **Golden template (correct text + bound arrows, brand palette):** use `templates/reliable-flowchart.excalidraw` as a minimal working reference.
+- **Other templates:** `templates/flowchart-template.excalidraw`, `templates/sequence-diagram-template.excalidraw`, and others in `templates/`.
+- **Scripts:** if present in `scripts/` (e.g. add-arrow), use them with brand palette; see `scripts/README.md` when available.