@atlashub/smartstack-cli 2.5.3 → 2.6.1

package/templates/skills/documentation/data-schema.md

@@ -2,68 +2,94 @@
 
 ## Purpose
 
-This file describes how to generate `frd-data.ts` files for the `FrdDocRenderer` shared component.
+This file describes how to generate `doc-data.ts` files for the `DocRenderer` shared component.
 Instead of generating full TSX components (~250 lines) per module, generate only the data (~50 lines).
 
-## FrdData Interface Reference
+## DocData Interface Reference
 
 The full TypeScript interface is in `web/smartstack-web/src/components/docs/types.ts`.
 
 ## Data Extraction Mapping
 
-### From FRD (3-functional-specification.md)
+### From feature.json (single source of truth)
 
-| FRD Section | FrdData Field | Extraction |
-|-------------|---------------|------------|
-| Section 1: Overview | `overview.objective` | Functional objective text |
-| Section 1: Overview | `overview.problem` | Problem statement |
-| Section 1: Overview | `overview.solution` | Solution statement |
-| Section 2: Use Cases | `useCases[]` | UC-XXX entries (id, name, actor, description, permission, priority) |
-| Section 3: Functional Requirements | `features[]` | FR-XXX entries grouped as features |
-| Section 5: Permission Matrix | `permissions[]` | Role-permission entries |
-| Section 6: Gherkin Scenarios | (used for test data, not doc) | - |
-| Section 7: Validations | `businessRules[]` | BR-XXX from BRD cross-referenced |
+The business analysis skill (`/business-analyse`) produces a `feature.json` file per module at:
+`docs/business/{app}/{module}/business-analyse/v{X.Y}/feature.json`
 
-### From BRD (2-business-requirements.md)
+All documentation data is extracted from this file.
 
-| BRD Section | FrdData Field | Extraction |
-|-------------|---------------|------------|
-| Section 2: Business Objectives | `overview.stats` | Count objectives |
-| Section 3: Business Rules | `businessRules[]` | BR-XXX entries (id, name, category, statement) |
-| Section 6: Integrations | `technicalRef` | Integration notes |
+#### Specification section → DocData fields
 
-### From Handoff (4-development-handoff.md)
+| feature.json Path | DocData Field | Extraction |
+|-------------------|---------------|------------|
+| `specification.useCases[]` | `useCases[]` | UC-XXX entries (id, name, actor, description, permission, priority) |
+| `specification.functionalRequirements[]` | `features[]` | FR-XXX entries grouped as features |
+| `specification.permissionsMatrix` | `permissions[]` | Role-permission entries |
+| `specification.apiEndpoints[]` | `apiEndpoints[]` | Endpoint entries (method, path, handler, permission) |
+| `specification.wireframes[]` | `steps[]` | Inferred from wireframe descriptions |
+| `specification.gherkinScenarios` | (used for test data, not doc) | - |
 
-| Handoff Section | FrdData Field | Extraction |
-|-----------------|---------------|------------|
-| Section 3: Files to Create | `technicalRef.entityNames` | Entity names |
-| Section 6: API Endpoints | `apiEndpoints[]` | Endpoint entries |
-| Section 1: Quick Context | `technicalRef.permissionBase` | Permission base path |
-| Section 1: Quick Context | `technicalRef.controllerRoute` | Controller route |
+#### Analysis section → DocData fields
+
+| feature.json Path | DocData Field | Extraction |
+|-------------------|---------------|------------|
+| `analysis.businessRules[]` | `businessRules[]` | BR-XXX entries (id, name, category, statement) |
+| `analysis.objectives[]` | `overview.stats` | Count objectives |
+| `analysis.entities[]` | `technicalRef.entityNames` | Entity names from analysis |
+| `analysis.integrations[]` | `technicalRef` | Integration notes |
+
+#### Discovery section → DocData fields
+
+| feature.json Path | DocData Field | Extraction |
+|-------------------|---------------|------------|
+| `discovery.problem` | `overview.problem` | Problem statement |
+| `discovery.scope.inScope` | `overview.objective` | Functional objective text |
+| `discovery.scope.outOfScope` | `overview.solution` | Solution statement (inferred) |
+| `discovery.risks[]` | (optional) | Risk documentation |
+
+#### Handoff section → DocData fields
+
+| feature.json Path | DocData Field | Extraction |
+|-------------------|---------------|------------|
+| `handoff.filesToCreate.domain` | `technicalRef.entityNames` | Entity names |
+| `handoff.apiEndpointSummary[]` | `apiEndpoints[]` | Endpoint entries (cross-validate) |
+| `handoff.brToCodeMapping[]` | `technicalRef` | BR-to-code mapping |
 
 ### Generated/Inferred Fields
 
 | Field | Source |
 |-------|--------|
-| `featureId` | From 00-context.md state |
-| `moduleName` | From 00-context.md state |
-| `applicationName` | From 00-context.md state |
-| `version` | "1.0" (initial) |
-| `benefits[]` | Inferred from BRD objectives or i18n |
+| `featureId` | `metadata.featureId` from feature.json |
+| `moduleName` | `metadata.moduleName` from feature.json |
+| `applicationName` | `metadata.applicationName` from feature.json |
+| `version` | `metadata.version` from feature.json |
+| `benefits[]` | Inferred from analysis objectives or i18n |
 | `beforeAfter` | Inferred from discovery problem/solution |
 | `steps[]` | Inferred from use cases main scenario |
 | `faq[]` | Inferred from discovery open questions |
 | `screenshots` | Convention: `/assets/docs/{module}/step-{N}.png` |
 
+## Fallback: No feature.json Available
+
+If no feature.json exists (e.g., module was created without `/business-analyse`),
+the `/documentation` skill extracts data directly from code:
+
+| Source | DocData Field | Extraction |
+|--------|---------------|------------|
+| Controller `[Http*]` attributes | `apiEndpoints[]` | Method, path, permission |
+| `Permissions.cs` constants | `permissions[]` | Permission paths |
+| `Domain/Entities/*.cs` | `technicalRef.entityNames` | Entity class names |
+| i18n JSON files | `overview`, `features` | Existing translations |
+
 ## Generated File Structure
 
-### frd-data.ts (per module, ~50-80 lines)
+### doc-data.ts (per module, ~50-80 lines)
 
 ```typescript
-// web/smartstack-web/src/pages/docs/business/{app}/{module}/frd-data.ts
-import type { FrdData } from '@/components/docs';
+// web/smartstack-web/src/pages/docs/business/{app}/{module}/doc-data.ts
+import type { DocData } from '@/components/docs';
 
-export const frdData: FrdData = {
+export const docData: DocData = {
   featureId: 'FEAT-001',
   moduleName: 'Sla',
   applicationName: 'Support',
@@ -142,13 +168,13 @@ export const frdData: FrdData = {
 
 ```typescript
 // web/smartstack-web/src/pages/docs/business/{app}/{module}/index.tsx
-import { FrdDocRenderer } from '@/components/docs';
-import { frdData } from './frd-data';
+import { DocRenderer } from '@/components/docs';
+import { docData } from './doc-data';
 
 export default function {Module}DocPage() {
   return (
-    <FrdDocRenderer
-      data={frdData}
+    <DocRenderer
+      data={docData}
       backPath="/docs/business/{app}"
       backLabel="nav.backToApp"
     />
@@ -169,14 +195,14 @@ export default function {Module}DocPage() {
         "solution": "Monitoring automatique des SLA avec alertes et escalades configurables"
       },
       "benefits": {
-        "time": { "title": "Temps économisé", "description": "Réduction de 70% du temps de suivi manuel" },
-        "quality": { "title": "Fiabilité", "description": "95% des SLA respectés grâce au monitoring" },
+        "time": { "title": "Temps economise", "description": "Reduction de 70% du temps de suivi manuel" },
+        "quality": { "title": "Fiabilite", "description": "95% des SLA respectes grace au monitoring" },
         "roi": { "title": "ROI", "description": "Retour sur investissement en 3 mois" }
       },
       "faq": {
         "1": {
           "question": "Dois-je configurer chaque SLA manuellement ?",
-          "answer": "Non, des templates prédéfinis sont disponibles pour les cas courants."
+          "answer": "Non, des templates predefinis sont disponibles pour les cas courants."
         }
       }
     }
@@ -184,7 +210,7 @@ export default function {Module}DocPage() {
 }
 ```
 
-> **Note:** Seul FR est généré. EN/IT/DE sont marqués comme "deferred" et générés par un pipeline de traduction séparé.
+> **Note:** Seul FR est genere. EN/IT/DE sont marques comme "deferred" et generes par un pipeline de traduction separe.
 
 ## Screenshot Convention
 
@@ -195,4 +221,4 @@ export default function {Module}DocPage() {
 | `dashboard` | `/assets/docs/{module}/dashboard.png` | Dashboard view |
 
 Screenshots are added manually or via Playwright E2E tests.
-The `FrdDocRenderer` shows a "Screenshot à venir" placeholder when the image file is not found.
+The `DocRenderer` shows a "Screenshot a venir" placeholder when the image file is not found.

package/templates/skills/documentation/templates.md

@@ -25,20 +25,20 @@ Chaque documentation de module DOIT inclure ces sections dans cet ordre:
 ## Data-Driven Approach (Recommended)
 
 > **Principe:** Au lieu de générer un composant TSX complet (~250 lignes) par module,
-> générer uniquement un fichier de DONNÉES (`frd-data.ts`, ~50 lignes) + un wrapper minimal.
-> Le rendu est assuré par le composant partagé `FrdDocRenderer` dans `web/.../components/docs/`.
+> générer uniquement un fichier de DONNÉES (`doc-data.ts`, ~50 lignes) + un wrapper minimal.
+> Le rendu est assuré par le composant partagé `DocRenderer` dans `web/.../components/docs/`.
 
 ### Fichiers à générer par module
 
-**1. Data file** (`frd-data.ts`) : Voir [data-schema.md](data-schema.md) pour le mapping complet.
+**1. Data file** (`doc-data.ts`) : Voir [data-schema.md](data-schema.md) pour le mapping complet.
 
 **2. Page wrapper** (`index.tsx`, ~10 lignes) :
 ```tsx
-import { FrdDocRenderer } from '@/components/docs';
-import { frdData } from './frd-data';
+import { DocRenderer } from '@/components/docs';
+import { docData } from './doc-data';
 
 export default function {ModuleName}DocPage() {
-  return <FrdDocRenderer data={frdData} backPath="/docs/business/{app}" />;
+  return <DocRenderer data={docData} backPath="/docs/business/{app}" />;
 }
 ```
 

package/templates/skills/ralph-loop/SKILL.md

@@ -214,8 +214,7 @@ Before ANY work, verify MCP servers:
   "source": {
     "type": "ba-handoff",
     "handoff_path": "path/to/4-development-handoff.md",
-    "frd_path": null,
-    "brd_path": null
+    "feature_json_path": null
   },
   "tasks": [
     {

package/templates/skills/ralph-loop/steps/step-01-task.md

@@ -51,7 +51,7 @@ SOURCE_PATH=${HANDOFF:-$BA_OUTPUT}
 - Read the handoff document
 - Derive tasks from its specifications (per-layer breakdown)
 - Set `source.type = "ba-handoff"` and `source.handoff_path`
-- Look for FRD and BRD in the same directory
+- Look for feature.json in the same directory
 
 **If no handoff:**
 - Generate task breakdown from `{task_description}`

package/templates/skills/ui-components/SKILL.md

@@ -11,7 +11,9 @@ description: |
   - User asks for tooltips or infobubbles
   - Creating a page with entity display
   - Managing disabled states with explanatory messages
-  Scope: Pages, Components, Cards, Tables, Grids, Kanban boards, Tooltips
+  - User mentions "dashboard", "chart", "kpi", "analytics", "graph"
+  - Creating a dashboard with KPI cards or charts
+  Scope: Pages, Components, Cards, Tables, Grids, Kanban boards, Tooltips, Dashboards, Charts
 ---
 
 # Skill UI Components SmartStack
@@ -26,6 +28,7 @@ description: |
 | List creation | "Display products in cards" |
 | Keywords | "card", "grid", "table", "kanban", "tooltip" |
 | Disabled states | "Disable button with explanatory message" |
+| Dashboard/Chart creation | "dashboard", "chart", "kpi", "analytics", "graph", "metrics" |
 
 ## Detailed patterns
 
@@ -33,6 +36,7 @@ description: |
 - For DataTable: [patterns/data-table.md](patterns/data-table.md)
 - For Grid layouts: [patterns/grid-layout.md](patterns/grid-layout.md)
 - For Kanban boards: [patterns/kanban.md](patterns/kanban.md)
+- For Dashboard & Charts: [patterns/dashboard-chart.md](patterns/dashboard-chart.md)
 - For styling rules: [style-guide.md](style-guide.md)
 - For accessibility: [accessibility.md](accessibility.md)
 
@@ -91,9 +95,36 @@ import { EntityCard, ProviderCard, TemplateCard } from '@/components/ui/EntityCa
 | EntityCard for entities | Custom cards with manual divs |
 | Responsive grid 1->2->3->4 | Fixed non-responsive grid |
 | h-full + flex-1 + mt-auto | Unaligned buttons in grid |
-| Empty and loading states | Native HTML tooltip |
+| Empty, loading, and error states | Native HTML tooltip |
 | Explicit TypeScript interfaces | `any` or implicit types |
 | `<button>` for click actions | `<div role="button">` |
 | `memo()` for list item components | Unmemoized components in loops |
 | `useCallback` for event handlers | Inline arrow functions in JSX |
 | Unique `id` for list keys | Array index as key |
+
+### Error States with Retry
+
+**ALWAYS provide user-friendly error states with retry capability.**
+
+```tsx
+{error && (
+  <div className="p-4 bg-[var(--error-bg)] border border-[var(--error-border)] rounded-[var(--radius-card)]">
+    <div className="flex items-center">
+      <AlertCircle className="h-5 w-5 text-[var(--error-text)]" />
+      <span className="ml-2 text-[var(--error-text)]">{error}</span>
+    </div>
+    <button
+      onClick={() => refetch()}
+      className="mt-2 text-sm text-[var(--error-text)] hover:opacity-80 underline"
+    >
+      {t('common:actions.retry')}
+    </button>
+  </div>
+)}
+```
+
+**Rules:**
+- Use semantic error CSS variables (`--error-bg`, `--error-border`, `--error-text`)
+- Always provide retry button for recoverable errors
+- Use Lucide `AlertCircle` icon (not inline SVG)
+- Keep error messages user-friendly (not technical stack traces)

package/templates/skills/ui-components/patterns/dashboard-chart.md

@@ -0,0 +1,327 @@
+# Dashboard & Chart Patterns
+
+> **Library:** Recharts (standardized for SmartStack)
+> **Install:** `npm install recharts` (add to package.json if absent)
+> **Reference:** https://recharts.org/
+
+## CRITICAL RULES
+
+1. **NEVER hardcode chart colors** - Use CSS variables (`--chart-1` to `--chart-5`)
+2. **NEVER hardcode text** - Use `useTranslation()` for all labels, tooltips, legends
+3. **ALWAYS use ResponsiveContainer** - Charts must be responsive
+4. **ALWAYS provide loading/error states** - Skeleton loaders for charts
+5. **ALWAYS use CSS variables** for backgrounds, borders, text (see style-guide.md)
+
+---
+
+## KPI CARD (StatCard)
+
+Use for single-value metrics with trend indicator.
+
+```tsx
+import { LucideIcon } from 'lucide-react';
+
+interface StatCardProps {
+  label: string;
+  value: string | number;
+  icon: LucideIcon;
+  trend?: { value: number; direction: 'up' | 'down' | 'flat' };
+  format?: 'number' | 'currency' | 'percent' | 'duration';
+}
+
+function StatCard({ label, value, icon: Icon, trend, format = 'number' }: StatCardProps) {
+  const formattedValue = formatValue(value, format);
+
+  return (
+    <div className="rounded-[var(--radius-card)] bg-[var(--bg-secondary)] border border-[var(--border-color)] p-6">
+      <div className="flex items-center justify-between">
+        <span className="text-sm font-medium text-[var(--text-muted)]">{label}</span>
+        <Icon className="h-5 w-5 text-[var(--color-primary-500)]" />
+      </div>
+      <div className="mt-2 text-2xl font-bold text-[var(--text-primary)]">
+        {formattedValue}
+      </div>
+      {trend && (
+        <div className={`mt-1 flex items-center text-sm ${
+          trend.direction === 'up' ? 'text-[var(--success-text)]' :
+          trend.direction === 'down' ? 'text-[var(--error-text)]' :
+          'text-[var(--text-muted)]'
+        }`}>
+          {trend.direction === 'up' ? '↑' : trend.direction === 'down' ? '↓' : '→'}
+          <span className="ml-1">{Math.abs(trend.value)}%</span>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### KPI Card with Thresholds
+
+```tsx
+function getThresholdColor(value: number, thresholds?: { warning: number; critical: number }) {
+  if (!thresholds) return 'text-[var(--text-primary)]';
+  if (value >= thresholds.critical) return 'text-[var(--error-text)]';
+  if (value >= thresholds.warning) return 'text-[var(--warning-text)]';
+  return 'text-[var(--success-text)]';
+}
+```
+
+---
+
+## CHART WRAPPER (ChartCard)
+
+Wraps any Recharts chart in a consistent card layout.
+
+```tsx
+interface ChartCardProps {
+  title: string;
+  subtitle?: string;
+  children: React.ReactNode;
+  height?: number;
+  loading?: boolean;
+}
+
+function ChartCard({ title, subtitle, children, height = 300, loading }: ChartCardProps) {
+  if (loading) {
+    return (
+      <div className="rounded-[var(--radius-card)] bg-[var(--bg-secondary)] border border-[var(--border-color)] p-6">
+        <div className="h-4 w-1/3 bg-[var(--bg-tertiary)] rounded animate-pulse mb-4" />
+        <div className="bg-[var(--bg-tertiary)] rounded animate-pulse" style={{ height }} />
+      </div>
+    );
+  }
+
+  return (
+    <div className="rounded-[var(--radius-card)] bg-[var(--bg-secondary)] border border-[var(--border-color)] p-6">
+      <h3 className="text-base font-semibold text-[var(--text-primary)]">{title}</h3>
+      {subtitle && (
+        <p className="text-sm text-[var(--text-muted)] mt-1">{subtitle}</p>
+      )}
+      <div className="mt-4" style={{ height }}>
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## CHART TYPES
+
+### Shared Tooltip Style
+
+```tsx
+const TOOLTIP_STYLE = {
+  contentStyle: {
+    backgroundColor: 'var(--bg-secondary)',
+    border: '1px solid var(--border-color)',
+    borderRadius: 'var(--radius-card)',
+    color: 'var(--text-primary)',
+    fontSize: '0.875rem',
+  },
+  labelStyle: {
+    color: 'var(--text-primary)',
+    fontWeight: 600,
+  },
+};
+```
+
+### Chart Color Palette
+
+```tsx
+const CHART_COLORS = [
+  'var(--chart-1)',
+  'var(--chart-2)',
+  'var(--chart-3)',
+  'var(--chart-4)',
+  'var(--chart-5)',
+];
+```
+
+### Bar Chart
+
+```tsx
+import { ResponsiveContainer, BarChart, Bar, XAxis, YAxis, Tooltip, CartesianGrid } from 'recharts';
+
+<ChartCard title={t('charts.itemsByMonth')}>
+  <ResponsiveContainer width="100%" height="100%">
+    <BarChart data={data}>
+      <CartesianGrid strokeDasharray="3 3" stroke="var(--border-color)" />
+      <XAxis dataKey="name" stroke="var(--text-muted)" fontSize={12} />
+      <YAxis stroke="var(--text-muted)" fontSize={12} />
+      <Tooltip {...TOOLTIP_STYLE} />
+      <Bar dataKey="value" fill="var(--chart-1)" radius={[4, 4, 0, 0]} />
+    </BarChart>
+  </ResponsiveContainer>
+</ChartCard>
+```
+
+### Stacked Bar Chart
+
+```tsx
+<ResponsiveContainer width="100%" height="100%">
+  <BarChart data={data}>
+    <CartesianGrid strokeDasharray="3 3" stroke="var(--border-color)" />
+    <XAxis dataKey="month" stroke="var(--text-muted)" fontSize={12} />
+    <YAxis stroke="var(--text-muted)" fontSize={12} />
+    <Tooltip {...TOOLTIP_STYLE} />
+    <Bar dataKey="active" stackId="a" fill="var(--chart-1)" />
+    <Bar dataKey="pending" stackId="a" fill="var(--chart-2)" />
+    <Bar dataKey="closed" stackId="a" fill="var(--chart-3)" radius={[4, 4, 0, 0]} />
+  </BarChart>
+</ResponsiveContainer>
+```
+
+### Line Chart
+
+```tsx
+import { ResponsiveContainer, LineChart, Line, XAxis, YAxis, Tooltip, CartesianGrid } from 'recharts';
+
+<ChartCard title={t('charts.trendOverTime')}>
+  <ResponsiveContainer width="100%" height="100%">
+    <LineChart data={data}>
+      <CartesianGrid strokeDasharray="3 3" stroke="var(--border-color)" />
+      <XAxis dataKey="date" stroke="var(--text-muted)" fontSize={12} />
+      <YAxis stroke="var(--text-muted)" fontSize={12} />
+      <Tooltip {...TOOLTIP_STYLE} />
+      <Line type="monotone" dataKey="value" stroke="var(--chart-1)" strokeWidth={2} dot={false} />
+      <Line type="monotone" dataKey="target" stroke="var(--chart-2)" strokeWidth={2} strokeDasharray="5 5" dot={false} />
+    </LineChart>
+  </ResponsiveContainer>
+</ChartCard>
+```
+
+### Pie / Donut Chart
+
+```tsx
+import { ResponsiveContainer, PieChart, Pie, Cell, Tooltip, Legend } from 'recharts';
+
+<ChartCard title={t('charts.distributionByStatus')}>
+  <ResponsiveContainer width="100%" height="100%">
+    <PieChart>
+      <Pie
+        data={data}
+        cx="50%"
+        cy="50%"
+        innerRadius={60}  // 0 for pie, >0 for donut
+        outerRadius={100}
+        dataKey="value"
+        nameKey="name"
+        label={({ name, percent }) => `${name} ${(percent * 100).toFixed(0)}%`}
+      >
+        {data.map((_, index) => (
+          <Cell key={index} fill={CHART_COLORS[index % CHART_COLORS.length]} />
+        ))}
+      </Pie>
+      <Tooltip {...TOOLTIP_STYLE} />
+      <Legend />
+    </PieChart>
+  </ResponsiveContainer>
+</ChartCard>
+```
+
+### Area Chart
+
+```tsx
+import { ResponsiveContainer, AreaChart, Area, XAxis, YAxis, Tooltip, CartesianGrid } from 'recharts';
+
+<ChartCard title={t('charts.volumeOverTime')}>
+  <ResponsiveContainer width="100%" height="100%">
+    <AreaChart data={data}>
+      <CartesianGrid strokeDasharray="3 3" stroke="var(--border-color)" />
+      <XAxis dataKey="date" stroke="var(--text-muted)" fontSize={12} />
+      <YAxis stroke="var(--text-muted)" fontSize={12} />
+      <Tooltip {...TOOLTIP_STYLE} />
+      <Area type="monotone" dataKey="value" stroke="var(--chart-1)" fill="var(--chart-1)" fillOpacity={0.2} />
+    </AreaChart>
+  </ResponsiveContainer>
+</ChartCard>
+```
+
+---
+
+## DASHBOARD LAYOUT
+
+### Standard Dashboard Grid
+
+```tsx
+interface DashboardLayoutProps {
+  kpis: StatCardProps[];
+  charts: ChartCardProps[];
+  filters?: React.ReactNode;
+  loading?: boolean;
+}
+
+function DashboardLayout({ kpis, charts, filters, loading }: DashboardLayoutProps) {
+  return (
+    <div className="space-y-6">
+      {/* Filters */}
+      {filters && (
+        <div className="flex flex-wrap items-center gap-4">
+          {filters}
+        </div>
+      )}
+
+      {/* KPI Row - 1 col mobile, 2 col tablet, 4 col desktop */}
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
+        {kpis.map((kpi, i) => (
+          <StatCard key={i} {...kpi} />
+        ))}
+      </div>
+
+      {/* Charts Row - 1 col mobile, 2 col desktop */}
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        {charts.map((chart, i) => (
+          <ChartCard key={i} {...chart} loading={loading} />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Period Filter
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+function PeriodFilter({ value, onChange }: { value: string; onChange: (v: string) => void }) {
+  const { t } = useTranslation();
+  const periods = [
+    { value: 'day', label: t('common:periods.day') },
+    { value: 'week', label: t('common:periods.week') },
+    { value: 'month', label: t('common:periods.month') },
+    { value: 'quarter', label: t('common:periods.quarter') },
+    { value: 'year', label: t('common:periods.year') },
+  ];
+
+  return (
+    <select
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      className="rounded-[var(--radius-button)] bg-[var(--bg-secondary)] border border-[var(--border-color)] text-[var(--text-primary)] px-3 py-1.5 text-sm"
+    >
+      {periods.map(p => (
+        <option key={p.value} value={p.value}>{p.label}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+---
+
+## ABSOLUTE RULES
+
+| DO | DON'T |
+|----|-------|
+| CSS variables for ALL chart colors (`--chart-1` to `--chart-5`) | Hardcoded hex colors (`fill="#8884d8"`) |
+| CSS variables for backgrounds/borders/text | Hardcoded Tailwind (`bg-blue-500`) |
+| `ResponsiveContainer width="100%" height="100%"` | Fixed pixel dimensions |
+| `useTranslation()` for labels and tooltips | Hardcoded text strings |
+| Skeleton loading states for charts | Blank space during loading |
+| Separate `StatCard` for KPI values | Inline divs with numbers |
+| `ChartCard` wrapper for consistent styling | Naked charts without card wrapper |
+| `memo()` for chart components in lists | Re-rendering charts on every state change |

package/templates/skills/ui-components/style-guide.md

@@ -40,6 +40,33 @@ const STATUS_CONFIG = {
 };
 ```
 
+### Chart Colors
+
+For data visualizations (Recharts), use dedicated chart CSS variables:
+
+| Variable | Usage | Example |
+|----------|-------|---------|
+| `--chart-1` | Primary data series | Main bar/line/area |
+| `--chart-2` | Secondary data series | Comparison line |
+| `--chart-3` | Tertiary data series | Third category |
+| `--chart-4` | Quaternary data series | Fourth category |
+| `--chart-5` | Quinary data series | Fifth category |
+
+These variables adapt automatically to light/dark theme.
+
+```tsx
+// CORRECT - CSS variable
+<Bar dataKey="value" fill="var(--chart-1)" />
+<Line stroke="var(--chart-2)" />
+<Cell fill={CHART_COLORS[index % CHART_COLORS.length]} />
+
+// WRONG - hardcoded colors
+<Bar dataKey="value" fill="#8884d8" />
+<Line stroke="blue" />
+```
+
+**See [patterns/dashboard-chart.md](patterns/dashboard-chart.md) for complete chart patterns.**
+
 ## BUTTON VARIANTS
 
 ### Action Buttons (Status changes)