docs(agent): streamline guidance and skills

Keep always-on instructions concise and route specialized work through focused skills. Split large skills into progressive references and add dedicated change, desktop, sync, and performance guidance.
2026-07-14 00:45:44 +03:00
parent b36afbf5ee
commit 68f1c1efe3
20 changed files with 1257 additions and 1371 deletions
@@ -0,0 +1,59 @@
+# Icon System
+
+## Contract
+
+Use `Icon` from `@/components/icon/Icon` and `IconName` from `@/components/icon/icons`. Do not import icon components directly from `@remixicon/react`.
+
+```tsx
+import { Icon } from '@/components/icon/Icon';
+import type { IconName } from '@/components/icon/icons';
+
+<Icon name="arrow-down-s" className="size-4" />
+```
+
+`Icon` has no `size` prop. Size it with classes.
+
+## Naming
+
+Convert Remixicon names to sprite names:
+
+1. Remove `Ri`.
+2. Remove the `Line` suffix.
+3. Convert PascalCase to lowercase kebab-case.
+4. Preserve filled variants with explicit `-fill`.
+
+| Remixicon | Sprite name |
+|---|---|
+| `RiArrowDownSLine` | `arrow-down-s` |
+| `RiCheckLine` | `check` |
+| `RiLoader4Line` | `loader-4` |
+| `RiGithubFill` | `github-fill` |
+
+## Config Values
+
+Store icon names, not component references:
+
+```tsx
+const items: Array<{ icon: IconName }> = [{ icon: 'stack' }];
+
+return <Icon name={items[0].icon} className="size-4" />;
+```
+
+Use literal inference (`as const`) only when the surrounding type does not already provide `IconName`.
+
+## Adding An Icon
+
+1. Use the correct kebab-case name in source.
+2. Type non-JSX values as `IconName`.
+3. Run `bun run icons:generate`.
+4. Inspect generated changes and run relevant type-check/build validation.
+
+Never edit `packages/ui/src/components/icon/sprite.ts` manually. The generator scans source usages, maps names to Remixicon, and regenerates the sprite.
+
+## Key Files
+
+- Component: `packages/ui/src/components/icon/Icon.tsx`
+- Types: `packages/ui/src/components/icon/icons.ts`
+- Generated sprite: `packages/ui/src/components/icon/sprite.ts`
+- Generator: `scripts/generate-icon-sprite.mjs`
+- Documentation: `packages/ui/src/components/icon/README.md`
@@ -0,0 +1,112 @@
+# Theme Tokens And Examples
+
+## Token Families
+
+### Surface
+
+| Token | Usage |
+|---|---|
+| `surface.background` | Main app background |
+| `surface.elevated` | Inputs, cards, panels, popovers |
+| `surface.muted` | Secondary backgrounds and sidebars |
+| `surface.foreground` | Primary text |
+| `surface.mutedForeground` | Secondary text and hints |
+| `surface.subtle` | Subtle dividers |
+
+### Interactive
+
+| Token | Usage |
+|---|---|
+| `interactive.border` | Default borders |
+| `interactive.hover` | Hover on clickable elements only |
+| `interactive.active` | Pressed interaction state |
+| `interactive.selection` | Active/selected items |
+| `interactive.selectionForeground` | Text on selection |
+| `interactive.focusRing` | Focus indicators |
+
+### Status
+
+Use status colors only for actual feedback.
+
+- `status.error`: errors and validation failures
+- `status.warning`: cautions
+- `status.success`: successful outcomes
+- `status.info`: informational feedback
+
+Each family may expose foreground, background, and border variants.
+
+### Primary
+
+- `primary.base`: primary CTA
+- `primary.hover`: primary hover
+- `primary.foreground`: content on primary
+
+Primary means “act”; selection means “currently active.” Do not use primary to mark ordinary selected tabs or rows.
+
+### Syntax
+
+Use `syntax.*` only for code display: code backgrounds/text, keywords, strings, and diff highlights. Never use syntax colors for ordinary UI chrome.
+
+## Usage
+
+Prefer semantic utility classes when available:
+
+```tsx
+<div className="bg-[var(--surface-elevated)] text-foreground" />
+<button className="hover:bg-interactive-hover" />
+```
+
+Use `useThemeSystem()` when a library/API requires actual color values:
+
+```tsx
+const { currentTheme } = useThemeSystem();
+
+<Chart color={currentTheme.colors.status.error} />
+```
+
+## Common Patterns
+
+### Input Area
+
+```tsx
+<div className="bg-[var(--surface-elevated)]">
+  <textarea className="bg-transparent" />
+  <div className="bg-transparent">...</div>
+</div>
+```
+
+Input footers stay transparent over the elevated input surface.
+
+### Active Item
+
+```tsx
+<button className={isActive
+  ? 'bg-interactive-selection text-interactive-selection-foreground'
+  : 'hover:bg-interactive-hover'
+} />
+```
+
+### Error Feedback
+
+```tsx
+<div className="bg-[var(--status-error-background)] text-[var(--status-error-foreground)]" />
+```
+
+### Neutral Card
+
+```tsx
+<section className="bg-[var(--surface-elevated)] text-foreground">
+  <p className="text-muted-foreground">...</p>
+</section>
+```
+
+## Wrong Patterns
+
+```tsx
+<div style={{ backgroundColor: '#F2F0E5' }} />
+<button className="bg-blue-500" />
+<div className="hover:bg-interactive-hover">Static content</div>
+<Tab className="bg-primary">Active</Tab>
+```
+
+Use theme tokens, apply hover only to interactive elements, and distinguish selection from primary actions.