siesa-agents 2.1.89 → 2.1.91

package/siesa-agents/wds/data/design-system/naming-conventions.md

@@ -0,0 +1,200 @@
+# Design System Naming Conventions
+
+**Purpose:** Consistent naming across design system components and tokens.
+
+**Referenced by:** Component-type instructions, design system operations
+
+---
+
+## Component IDs
+
+**Format:** `[type-prefix]-[number]`
+
+**Prefixes:**
+
+- btn = Button
+- inp = Input Field
+- chk = Checkbox
+- rad = Radio
+- tgl = Toggle
+- drp = Dropdown
+- mdl = Modal
+- crd = Card
+- alt = Alert
+- bdg = Badge
+- tab = Tab
+- acc = Accordion
+
+**Examples:**
+
+- `btn-001` = First button component
+- `inp-002` = Second input field component
+- `mdl-001` = First modal component
+
+**Rules:**
+
+- Always lowercase
+- Always hyphenated
+- Always zero-padded (001, not 1)
+- Sequential within type
+
+---
+
+## Component Names
+
+**Format:** `[Type] [Descriptor]` or just `[Type]`
+
+**Examples:**
+
+- `Button` (generic)
+- `Navigation Button` (specific)
+- `Primary Button` (variant-focused)
+- `Icon Button` (visual-focused)
+
+**Rules:**
+
+- Title case
+- Descriptive but concise
+- Avoid redundancy (not "Button Button")
+
+---
+
+## Variant Names
+
+**Format:** Lowercase, hyphenated
+
+**Purpose-Based:**
+
+- `primary` - Main action
+- `secondary` - Secondary action
+- `destructive` - Delete/remove
+- `success` - Positive confirmation
+- `warning` - Caution
+- `navigation` - Navigation action
+
+**Visual-Based:**
+
+- `outlined` - Border, no fill
+- `ghost` - Transparent background
+- `solid` - Filled background
+
+**Size-Based:**
+
+- `small` - Compact
+- `medium` - Default
+- `large` - Prominent
+
+**Rules:**
+
+- Lowercase
+- Hyphenated for multi-word
+- Semantic over visual when possible
+
+---
+
+## State Names
+
+**Standard States:**
+
+- `default` - Normal state
+- `hover` - Mouse over
+- `active` - Being clicked/pressed
+- `focus` - Keyboard focus
+- `disabled` - Cannot interact
+- `loading` - Processing
+- `error` - Error state
+- `success` - Success state
+- `warning` - Warning state
+
+**Rules:**
+
+- Lowercase
+- Single word preferred
+- Use standard names when possible
+
+---
+
+## Design Token Names
+
+**Format:** `--{category}-{property}-{variant}`
+
+**Color Tokens:**
+
+```
+--color-primary-500
+--color-gray-900
+--color-success-600
+--color-error-500
+```
+
+**Typography Tokens:**
+
+```
+--text-xs
+--text-base
+--text-4xl
+--font-normal
+--font-bold
+```
+
+**Spacing Tokens:**
+
+```
+--spacing-1
+--spacing-4
+--spacing-8
+```
+
+**Component Tokens:**
+
+```
+--button-padding-x
+--input-border-color
+--card-shadow
+```
+
+**Rules:**
+
+- Kebab-case
+- Hierarchical (general → specific)
+- Semantic names preferred
+
+---
+
+## File Names
+
+**Component Files:**
+
+```
+button.md
+navigation-button.md
+input-field.md
+```
+
+**Rules:**
+
+- Lowercase
+- Hyphenated
+- Match component name (simplified)
+
+---
+
+## Folder Names
+
+```
+components/
+design-tokens/
+operations/
+assessment/
+templates/
+```
+
+**Rules:**
+
+- Lowercase
+- Hyphenated
+- Plural for collections
+
+---
+
+**Consistency in naming makes the design system easier to navigate and maintain.**

package/siesa-agents/wds/data/design-system/state-management.md

@@ -0,0 +1,93 @@
+# Component State Management
+
+**Purpose:** Guidelines for defining and managing component states.
+
+**Referenced by:** Component-type instructions (Button, Input, etc.)
+
+---
+
+## Standard States
+
+### Interactive Components (Buttons, Links)
+
+**Required:**
+
+- `default` - Normal, ready for interaction
+- `hover` - Mouse over component
+- `active` - Being clicked/pressed
+- `disabled` - Cannot interact
+
+**Optional:**
+
+- `loading` - Processing action
+- `focus` - Keyboard focus
+
+### Form Components (Inputs, Selects)
+
+**Required:**
+
+- `default` - Empty, ready for input
+- `focus` - Active input
+- `filled` - Has content
+- `disabled` - Cannot edit
+
+**Optional:**
+
+- `error` - Validation failed
+- `success` - Validation passed
+- `loading` - Fetching data
+
+### Feedback Components (Alerts, Toasts)
+
+**Required:**
+
+- `default` - Neutral information
+- `success` - Positive feedback
+- `error` - Error feedback
+- `warning` - Caution feedback
+
+---
+
+## State Naming
+
+**Use standard names:**
+
+- ✅ `hover` not `mouseover`
+- ✅ `disabled` not `inactive`
+- ✅ `loading` not `processing`
+
+**Be consistent across components.**
+
+---
+
+## State Transitions
+
+**Define how states change:**
+
+```yaml
+Button States: default → hover (mouse enters)
+  hover → active (mouse down)
+  active → hover (mouse up)
+  hover → default (mouse leaves)
+  any → disabled (programmatically)
+  any → loading (action triggered)
+```
+
+---
+
+## Visual Indicators
+
+**Each state should be visually distinct:**
+
+```yaml
+Button:
+  default: blue background
+  hover: darker blue + scale 1.02
+  active: darkest blue + scale 0.98
+  disabled: gray + opacity 0.6
+  loading: disabled + spinner
+```
+
+---
+
+**Reference this when specifying component states.**