npm - aibos-design-system - Versions diffs - 1.0.0 → 1.0.1 - Mend

aibos-design-system 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/LICENSE +21 -0
package/README.md +335 -333
package/dist/headless-map.json +44 -41
package/dist/tokens/index.d.ts +66 -66
package/dist/tokens.json +34 -34
package/{API_REFERENCE.md → docs/API_REFERENCE.md} +379 -379
package/{EXTERNAL_USAGE.md → docs/EXTERNAL_USAGE.md} +372 -370
package/docs/INTEGRATION_GUIDE.md +433 -0
package/docs/QUICK_REFERENCE.md +303 -0
package/input.css +4056 -4050
package/lib/cli-autocomplete.ts +231 -0
package/lib/cli-commands.ts +364 -0
package/lib/cli-filter-engine.ts +271 -0
package/lib/cli-parser.ts +197 -0
package/lib/utils.ts +18 -0
package/package.json +11 -4
package/style.css +683 -237

package/docs/INTEGRATION_GUIDE.md ADDED Viewed

@@ -0,0 +1,433 @@
+# Integration Guide
+**How to use Neo-Analog design tokens in your projects**
+---
+## Installation
+```bash
+npm install @aibos/design-system
+# or
+pnpm add @aibos/design-system
+```
+---
+## 1. CSS/HTML Projects
+### Import the compiled stylesheet:
+```html
+<head>
+  <link rel="stylesheet" href="node_modules/@aibos/design-system/style.css">
+</head>
+```
+### Use tokens in CSS:
+```css
+.my-button {
+  background-color: var(--color-gold);
+  color: var(--color-void);
+  padding: var(--spacing-4);
+  border-radius: var(--radius-control);
+  font-size: var(--font-size-base);
+  font-weight: var(--font-weight-semibold);
+  transition: background-color var(--duration-200) var(--ease-premium);
+}
+```
+### Use token classes in HTML:
+```html
+<div class="text-lux bg-paper rounded-card p-6 shadow-card">
+  <h3 class="na-h3">Card Title</h3>
+  <div class="na-data">$12,450.00</div>
+  <div class="na-metadata">Updated 2 hours ago</div>
+</div>
+```
+---
+## 2. React Projects
+### Import stylesheet:
+```tsx
+import '@aibos/design-system/style.css';
+```
+### Use tokens in CSS-in-JS (Emotion, styled-components):
+**Styled Components:**
+```tsx
+import styled from 'styled-components';
+const Card = styled.div`
+  background-color: var(--color-paper);
+  padding: var(--spacing-6);
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-card);
+`;
+export default function MyComponent() {
+  return (
+    <Card>
+      <h3 className="na-h3">Title</h3>
+      <div className="na-data">Value</div>
+    </Card>
+  );
+}
+```
+**Emotion:**
+```tsx
+import { css } from '@emotion/react';
+const cardStyles = css`
+  background-color: var(--color-paper);
+  padding: var(--spacing-6);
+  border-radius: var(--radius-card);
+`;
+export default function MyComponent() {
+  return <div css={cardStyles}>Content</div>;
+}
+```
+### Use Tailwind CSS with tokens:
+All tokens are available as Tailwind utilities:
+```tsx
+export default function MyComponent() {
+  return (
+    <div className="bg-paper p-6 rounded-card shadow-card">
+      <h3 className="na-h3">Title</h3>
+      <button className="bg-gold text-void px-4 py-3 rounded-control">
+        Action
+      </button>
+    </div>
+  );
+}
+```
+### Get tokens programmatically:
+```tsx
+import tokens from '@aibos/design-system/dist/tokens.json';
+const spacing = tokens.spacing['6']; // "1.5rem"
+const color = tokens.colors.gold;   // "#eab308"
+```
+---
+## 3. Vue Projects
+### Import stylesheet:
+```js
+// main.js
+import '@aibos/design-system/style.css';
+```
+### Use tokens in Vue components:
+```vue
+<template>
+  <div class="bg-paper p-6 rounded-card shadow-card">
+    <h3 class="na-h3">{{ title }}</h3>
+    <div class="na-data">{{ value }}</div>
+  </div>
+</template>
+<script setup>
+defineProps({
+  title: String,
+  value: String,
+});
+</script>
+<style scoped>
+.card {
+  background-color: var(--color-paper);
+  padding: var(--spacing-6);
+  border-radius: var(--radius-card);
+}
+</style>
+```
+---
+## 4. Tailwind CSS Integration
+### Configure tailwind.config.js:
+```js
+import { colors, spacing } from '@aibos/design-system/dist/tokens.json';
+export default {
+  theme: {
+    extend: {
+      colors,
+      spacing,
+    },
+  },
+};
+```
+### Use in templates:
+```html
+<div class="bg-paper p-6 rounded-card text-lux">
+  <h3 class="text-2xl font-bold">Title</h3>
+  <p class="text-clay">Subtitle</p>
+</div>
+```
+---
+## 5. TypeScript Projects
+### Import type definitions:
+```ts
+import type { DesignTokens } from '@aibos/design-system/dist/tokens/index.d.ts';
+const tokens: DesignTokens = require('@aibos/design-system/dist/tokens.json');
+// Fully typed token access
+const primaryColor: string = tokens.colors.gold;
+const padding: string = tokens.spacing['6'];
+```
+### Create typed theme hook (React):
+```tsx
+import tokens from '@aibos/design-system/dist/tokens.json';
+import type { DesignTokens } from '@aibos/design-system/dist/tokens/index.d.ts';
+export function useDesignTokens(): DesignTokens {
+  return tokens;
+}
+// Usage
+const MyComponent = () => {
+  const tokens = useDesignTokens();
+  return (
+    <div style={{ color: tokens.colors.lux }}>
+      Content
+    </div>
+  );
+};
+```
+---
+## 6. Figma Integration
+### Export tokens from Figma:
+1. Open Figma design file
+2. Use Design System → Export Tokens
+3. Paste exported JSON into your project's token file
+### Keep tokens in sync:
+```bash
+# Update from Figma
+npm run update:tokens
+# Rebuild CSS
+npm run build
+```
+---
+## 7. Headless/CSS-Only Projects
+### Use CSS variables directly:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="node_modules/@aibos/design-system/style.css">
+  <style>
+    body {
+      background: var(--color-void);
+      color: var(--color-lux);
+      font-family: var(--font-family-sans);
+      font-size: 15px;
+      line-height: 1.6;
+    }
+    .card {
+      background: var(--color-paper);
+      padding: var(--spacing-6);
+      border-radius: var(--radius-card);
+      box-shadow: var(--shadow-card);
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h2 class="na-h2">Card Title</h2>
+    <p class="na-data">Card content</p>
+  </div>
+</body>
+</html>
+```
+---
+## 8. Component Libraries
+### Build on Neo-Analog tokens:
+```tsx
+// Button.tsx
+import '@aibos/design-system/style.css';
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'ghost';
+  size: 'sm' | 'md' | 'lg';
+  children: React.ReactNode;
+}
+export const Button = ({ variant, size, children }: ButtonProps) => {
+  const variantClasses = {
+    primary: 'bg-gold text-void',
+    secondary: 'bg-paper text-lux border border-stroke',
+    ghost: 'text-lux hover:bg-paper-2',
+  };
+  const sizeClasses = {
+    sm: 'px-3 py-2 text-sm',
+    md: 'px-4 py-3 text-base',
+    lg: 'px-6 py-4 text-lg',
+  };
+  return (
+    <button
+      className={`
+        rounded-control font-semibold transition-all duration-200
+        ${variantClasses[variant]} ${sizeClasses[size]}
+      `}
+    >
+      {children}
+    </button>
+  );
+};
+```
+---
+## Common Patterns
+### Card Container:
+```html
+<div class="bg-paper p-6 rounded-card shadow-card border border-stroke">
+  <h3 class="na-h3">Card Title</h3>
+  <p class="text-clay">Card description</p>
+</div>
+```
+### Form Field:
+```html
+<div class="na-field">
+  <label class="na-label">Field Label</label>
+  <input
+    class="na-input border border-stroke rounded-control p-3"
+    type="text"
+  />
+  <p class="na-metadata mt-2">Help text</p>
+</div>
+```
+### Button Group:
+```html
+<div class="flex gap-3">
+  <button class="bg-gold text-void px-4 py-3 rounded-control font-semibold">
+    Primary
+  </button>
+  <button class="bg-paper text-lux px-4 py-3 rounded-control border border-stroke">
+    Secondary
+  </button>
+</div>
+```
+### Data Table:
+```html
+<table class="w-full">
+  <thead>
+    <tr class="bg-paper-2 border-b border-stroke">
+      <th class="na-label p-4">Column</th>
+      <th class="na-label p-4">Value</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr class="border-b border-stroke-soft hover:bg-paper-2">
+      <td class="p-4 text-lux">Row data</td>
+      <td class="p-4 na-data">$1,234.00</td>
+    </tr>
+  </tbody>
+</table>
+```
+---
+## Troubleshooting
+### Tokens not loading:
+```bash
+# Verify install
+npm list @aibos/design-system
+# Rebuild
+npm run build
+```
+### Colors not applying:
+```css
+/* Ensure CSS is imported before custom styles */
+@import '@aibos/design-system/style.css';
+/* Then use tokens */
+.element {
+  color: var(--color-lux); /* ✅ Works */
+}
+```
+### Missing utilities:
+Check [TOKEN_REFERENCE.md](TOKEN_REFERENCE.md) for available tokens.
+Custom utilities available:
+- `.na-h1` through `.na-h6` — Typography hierarchy
+- `.na-data`, `.na-data-large` — Data display
+- `.na-metadata`, `.na-metadata-small` — Metadata
+- `.text-lux`, `.text-clay`, `.text-gold` — Colors
+- `.bg-void`, `.bg-paper`, `.bg-paper-2` — Backgrounds
+---
+## Next Steps
+1. **Read** [TOKEN_REFERENCE.md](TOKEN_REFERENCE.md) — Complete token catalog
+2. **Review** [GOVERNANCE.md](GOVERNANCE.md) — Design system rules
+3. **Copy** examples from [DESIGN_SYSTEM.md](../DESIGN_SYSTEM.md) — Full guide
+---
+**Package:** [@aibos/design-system](https://www.npmjs.com/package/@aibos/design-system)
+**Last Updated:** 2025-01-24
+**Support:** Check documentation or open an issue on GitHub

package/docs/QUICK_REFERENCE.md ADDED Viewed

@@ -0,0 +1,303 @@
+# 🎯 CLI Reactive HUD - Quick Reference Card
+## Filter Syntax Cheat Sheet
+### Basic Filters
+```
+status:healthy              Single enum value
+owner:patel                String equality
+revenue>100000             Numeric comparison
+health>=80                 Greater or equal
+```
+### Operators Reference
+| Op | Meaning | Type | Example |
+|----|---------|------|---------|
+| `:` | Equals (default) | String/Enum | `status:healthy` |
+| `=` | Equals | Any | `status=healthy` |
+| `!=` | Not equal | Any | `status!=error` |
+| `>` | Greater than | Number | `revenue>100000` |
+| `<` | Less than | Number | `health<50` |
+| `>=` | Greater/equal | Number | `health>=80` |
+| `<=` | Less/equal | Number | `revenue<=250000` |
+### Compound Filters (AND Logic)
+```
+status:healthy revenue>100000
+→ Accounts with status="healthy" AND revenue > $100,000
+status:healthy revenue>100000 health>=80
+→ Accounts with ALL three conditions
+status:watch owner:chen
+→ Accounts with status="watch" AND owner="chen"
+```
+---
+## Available Filter Keys (25+)
+### Account Info
+- `account` - Account name
+- `status` - Status (healthy, watch, error)
+- `owner` - Owner name
+- `priority` - Priority level
+### Financial
+- `revenue` - Annual revenue ($)
+- `monthlyrev` - Monthly revenue
+- `growth` - Growth rate (%)
+### Health & Risk
+- `health` - Health score (0-100)
+- `score` - Overall score
+- `riskLevel` - Risk classification
+### Operational
+- `region` - Geographic region
+- `product` - Product category
+- `team` - Assigned team
+- `vol` - Volatility (low/medium/high)
+### Status Categories
+- `watch` - Watch list status
+- `error` - Error flag status
+- `critical` - Critical alerts
+### Metrics
+- `customMetric` - Custom data field
+- `tags` - Tag classification
+---
+## HUD Metrics Explained
+### 📊 Governed Revenue
+```
+Total:   Sum of all filtered account revenues
+         Example: $272,520 for 3 accounts
+Average: Total ÷ count of filtered accounts
+         Example: $136,260 per account
+```
+### 💚 Avg Health
+```
+Score:   Average health score (0-100%)
+         Example: 75%
+Trend:   ↗ Trending up (avg health > 80%)
+         → Stable (50-80% health)
+         ↘ Trending down (avg health < 50%)
+Status:  Distribution of status values
+         Example: "3 ↔ 1 accounts" = 3 healthy, 1 watch
+```
+### ⚠️ Risk Level
+```
+LOW:      Green badge - No watch/error accounts
+MEDIUM:   Yellow badge - Some risk indicators
+HIGH:     Orange badge - Multiple risk factors
+CRITICAL: Red badge - Serious risk situation
+Calculation:
+  watchCount = accounts with status='watch'
+  criticalCount = accounts with health < 40
+  riskScore = (watch × 0.5) + (critical × 0.3)
+```
+### 📌 Accounts
+```
+Count:       Number of matching records
+Description: Summary text
+             "6 accounts analyzed. 75% avg health. ✓ Clean"
+```
+---
+## Keyboard Navigation
+### In CLI Input
+| Key | Action |
+|-----|--------|
+| Type | Enter filter query |
+| Backspace | Delete character |
+| Ctrl+A | Select all |
+### In Autocomplete Menu (when visible)
+| Key | Action |
+|-----|--------|
+| ↓ | Next suggestion |
+| ↑ | Previous suggestion |
+| Enter | Insert selected suggestion |
+| Escape | Close menu |
+| Backspace | Delete & re-suggest |
+---
+## Test Scenarios
+### Scenario 1: Basic Filter
+**Query**: `status:healthy`
+- Shows: 3 healthy accounts
+- Revenue: $272,520 total, $90,840 average
+- Health: 79% average with trend
+- Risk: LOW (all healthy)
+- Count: 3 accounts
+### Scenario 2: Financial Filter
+**Query**: `revenue>100000`
+- Shows: 4 accounts with revenue > $100k
+- Revenue: Very high totals
+- Health: Mixed scores
+- Risk: Depends on health
+### Scenario 3: High-Risk
+**Query**: `health<50`
+- Shows: 2 high-risk accounts
+- Revenue: Lower revenues
+- Health: 39% average
+- Risk: CRITICAL (low health)
+### Scenario 4: Combined
+**Query**: `status:healthy revenue>100000`
+- Shows: Only 2 healthy accounts with high revenue
+- Most optimal accounts by both metrics
+- Health: 88% and 75%
+- Risk: LOW
+### Scenario 5: No Matches
+**Query**: `status:error health>90`
+- Shows: Empty state message
+- HUD: Reset to defaults
+- Table: No rows visible
+---
+## Integration Checklist
+- [ ] Copy `lib/` folder to your project
+- [ ] Add CLI imports to your module: `import { FilterEngine } from './lib/cli-filter-engine.ts'`
+- [ ] Create filter input element with id `cli-input`
+- [ ] Create HUD card elements (revenue, health, risk, count)
+- [ ] Wire filter input to `updateTable()` function
+- [ ] Bind `aggregateMetrics()` results to HUD DOM elements
+- [ ] Test with sample data (minimum 6 rows recommended)
+- [ ] Customize filter commands in `COMMAND_SCHEMA`
+- [ ] Add custom metrics to `aggregateMetrics()`
+- [ ] Style HUD cards with your brand colors
+---
+## Common Issues & Solutions
+### Issue: Autocomplete not appearing
+**Solution**: Make sure `li-cli-autocomplete.ts` is imported and autocomplete div exists in HTML
+### Issue: Metrics showing $0 or 0%
+**Solution**: Check that data attributes match command keys exactly (e.g., `data-revenue`, `data-health`)
+### Issue: Filter not working
+**Solution**: Verify command key exists in `COMMAND_SCHEMA` in `cli-commands.ts`
+### Issue: Type errors in TypeScript
+**Solution**: Ensure `ValidCommand` type is imported and used for all filter key references
+### Issue: HUD not updating
+**Solution**: Call `aggregateMetrics()` after `applyFilters()`, then update DOM elements
+---
+## Performance Tips
+### For Small Datasets (< 100 rows)
+- No optimization needed
+- All operations < 5ms
+- Real-time filtering safe
+### For Medium Datasets (100-1000 rows)
+- Consider debouncing input: `debounce(updateTable, 100ms)`
+- Batch DOM updates
+- Pre-calculate common metrics
+### For Large Datasets (1000+ rows)
+- Move filtering to server
+- Use pagination (load first 100 rows)
+- Cache aggregations
+- Use Web Workers for calculations
+---
+## Customization Guide
+### Add New Filter Command
+```typescript
+// In lib/cli-commands.ts
+export const COMMAND_SCHEMA: Record<ValidCommand, CommandSchema> = {
+  // ...existing...
+  newfilter: {
+    description: 'My custom filter',
+    type: 'enum',
+    values: ['option1', 'option2'],
+    operators: ['=', '!=']
+  }
+}
+// Add to ValidCommand type
+type ValidCommand = '...' | 'newfilter'
+// In HTML table
+<tr data-newfilter="option1">
+```
+### Add New HUD Metric
+```javascript
+// In FilterEngine.aggregateMetrics()
+return {
+  ...existing,
+  customMetric: {
+    value: calculateCustomValue(rows),
+    label: 'Custom Metric'
+  }
+}
+// In HTML
+<div class="hud-card">
+  <div class="hud-card-label">🎯 Custom</div>
+  <div class="hud-card-value" id="hud-custom">0</div>
+</div>
+// In updateTable()
+hudCustom.textContent = metrics.customMetric.value;
+```
+---
+## Browser Support
+- ✅ Chrome/Edge (latest 2 versions)
+- ✅ Firefox (latest 2 versions)
+- ✅ Safari (latest 2 versions)
+- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
+**Requires**:
+- ES2020+ support (optional chaining, nullish coalescing)
+- CSS Grid & Flexbox
+- Intl.NumberFormat API
+---
+## Related Documentation
+- 📖 [Complete Guide](CLI_REACTIVE_HUD_COMPLETE_GUIDE.md)
+- 🔧 [Integration Guide](INTEGRATION_GUIDE.md)
+- 📋 [Command Reference](CLI_FILTER_COMMANDS.md)
+- 🤖 [Autocomplete Deep Dive](CLI_AUTOCOMPLETE_ENGINE.md)
+- ✅ [Status Report](CLI_REACTIVE_HUD_FINAL_STATUS.md)
+---
+**Version**: 1.0
+**Last Updated**: December 29, 2025
+**Status**: Production Ready ✅