diff --git a/AGENTS.md b/AGENTS.md index 92be669a..83dabc54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,11 +60,48 @@ ForgePlan/ ├── templates/ ← markdown templates for each artifact kind ├── website/ ← official website (Astro + Starlight) ├── marketplace/ ← plugin marketplace (plugins + skills) +├── design/ ← design assets (forgeplan-design-system/ — canonical DS; Pencil .pen files later) ├── scripts/ ← build + release + helper scripts ├── Formula/ ← Homebrew formula └── .local/ ← gitignored — local notes, research, sessions ``` +## Design system (single source of truth) + +**`design/forgeplan-design-system/`** — the canonical, portable ForgePlan design system package. **Consult it whenever the task involves UI, styling, branding, colors, typography, components, web pages, slides, diagrams, README visuals, or any user-facing surface** — before writing any CSS/HTML/component code. + +Package contents (self-contained, no build step, no external deps): + +| File | Purpose | +|---|---| +| `DESIGN-SYSTEM.ru.md` / `.en.md` | Canonical documentation: palette, contrast table, typography, spacing, components, accessibility, print, per-surface rules | +| `tokens.css` | Drop-in CSS custom properties for dark + light themes (`data-theme` attribute) | +| `tokens.graph.css` | Optional module for graph/map/canvas surfaces (relation edges, canvas strokes, composed-map zones, dot-grid) — load after `tokens.css` | +| `tokens.json` | Machine-readable token contract with fact/proposal status per token | +| `components.html` | Self-contained bilingual component reference with theme switcher — open in browser | +| `cheatsheet.ru.html` / `.en.html` | A4 landscape quick references with print styles | + +Key invariants (details in the docs above): + +- **One accent:** `--forge-ember #FF6B35`. Legacy `--accent #FF5A1F` is deprecated — never use in new code. +- **Light-theme text accent:** `--forge-ember-text #C94400` (orange fails WCAG as text on light bg; ember stays for fills/borders/focus). +- **Radius 0 by default** (2px chips, 3px inline code, 50% avatars/dots only). No shadows — flatness via `1px solid var(--forge-line)`. +- **Fonts:** Space Grotesk (UI/text) + Geist Mono (code, IDs, R_eff numbers, metadata). +- **Layout:** `max-width 1280px`, `32px` gutter, sticky elements use `top: var(--header-h)` (88px full / 36px compact). +- **Reuse rule:** to apply the system elsewhere, copy the whole `design/forgeplan-design-system/` directory and link `tokens.css`; do not re-derive values from `website/` source (the blog theme diverges — it is documented tech debt). + +`design/` is the home for **all** design assets: + +- `forgeplan-design-system/` — the canonical package above, plus `brand-assets/` (logo SVGs, favicons, icons) +- `forgeplan-site.pen` — Pencil source file (site mockups + the design system as atomic-design components: Atoms → Molecules → Organisms → Layouts) +- `visual-guides/` — approved raster methodology guides (design-system foundation, quick start, 9 thematic 16:9 sheets) +- `command-map/` — command map by scenario (portrait + 16:9) +- `source-materials/` — source briefs for the guide set +- `MANIFEST.md` — exact file inventory +- `snapshots//` — CANVAS pipeline DS snapshot exports (when the pipeline runs) + +The design system follows **atomic design**: tokens → atoms → molecules → organisms → templates/layouts. Higher layers are composed from lower-layer components (refs, not copies). + ## Language - **Documentation & commit bodies:** Russian preferred (matches project conventions) @@ -100,3 +137,4 @@ If a future contributor joins, this section will be updated to reflect multi-aut - [`docs/methodology/FORGEPLAN-GUIDE.md`](docs/methodology/FORGEPLAN-GUIDE.md) — full methodology reference - [`docs/operations/AGENT-ENFORCEMENT.md`](docs/operations/AGENT-ENFORCEMENT.md) — agent rules and guardrails - [`website/README.md`](website/README.md) — website architecture notes +- [`design/forgeplan-design-system/README.md`](design/forgeplan-design-system/README.md) — canonical design system package (tokens, components, cheatsheets) diff --git a/design/MANIFEST.md b/design/MANIFEST.md new file mode 100644 index 00000000..12f2baad --- /dev/null +++ b/design/MANIFEST.md @@ -0,0 +1,40 @@ +# Manifest + +## Design system + +| File | Purpose | +| --- | --- | +| `design-system/DESIGN-SYSTEM.ru.md` | Каноническая русская документация | +| `design-system/DESIGN-SYSTEM.en.md` | Canonical English documentation | +| `design-system/tokens.css` | CSS custom properties, dark and light themes | +| `design-system/tokens.json` | Machine-readable token contract | +| `design-system/components.html` | Self-contained bilingual component reference | +| `design-system/cheatsheet.ru.html` | Русская A4-шпаргалка с print CSS | +| `design-system/cheatsheet.en.html` | English A4 reference with print CSS | +| `design-system/brand-assets/*` | SVG, PNG and ICO assets from the current site source | + +## Visual guides + +| File | Topic | Pixels | +| --- | --- | ---: | +| `visual-guides/00-design-system-foundation.png` | Основа дизайн-системы | 1672×941 | +| `visual-guides/01-quick-start-portrait.png` | Quick Start | 864×1821 | +| `visual-guides/02-development-cycle-16x9.png` | Полный цикл разработки | 1672×941 | +| `visual-guides/03-depth-selection-16x9.png` | Выбор глубины | 1672×941 | +| `visual-guides/04-artifact-types-16x9.png` | 10 типов артефактов | 1672×941 | +| `visual-guides/05-create-and-work-16x9.png` | Создание и работа с записями | 1672×941 | +| `visual-guides/06-diagnostics-and-agents-16x9.png` | Диагностика и агенты | 1672×941 | +| `visual-guides/07-evidence-protocol-16x9.png` | Evidence Protocol | 1672×941 | +| `visual-guides/08-reliability-fgr-16x9.png` | Надёжность и F·G·R | 1672×941 | +| `visual-guides/09-lifecycle-16x9.png` | Жизненный цикл записи | 1672×941 | +| `visual-guides/10-daily-work-16x9.png` | Ежедневная работа | 1672×941 | + +## Command map + +| File | Composition | Pixels | +| --- | --- | ---: | +| `command-map/forgeplan-command-map-a4-portrait.png` | Вертикальная печатная композиция | 1024×1536 | +| `command-map/forgeplan-command-map-16x9.png` | Горизонтальная экранная композиция | 1672×941 | + +Обе карты сгруппированы по семи сценариям: старт и маршрутизация; поиск и чтение; создание и изменение; проверка и рассуждение; Evidence и связи; жизненный цикл; диагностика и агенты. + diff --git a/design/README.md b/design/README.md new file mode 100644 index 00000000..b4e2ccaf --- /dev/null +++ b/design/README.md @@ -0,0 +1,39 @@ +# ForgePlan Complete Pack v1.0 + +Единый пакет дизайн-системы, визуальных гайдов и справочных карт ForgePlan. + +## Состав + +- `design-system/` — полная документация на русском и английском, CSS- и JSON-токены, self-contained HTML-компоненты, печатные справочники и бренд-ассеты. +- `visual-guides/` — принятые растровые схемы ForgePlan: основа дизайн-системы, Quick Start и девять тематических листов. +- `command-map/` — финальная карта команд по сценариям работы в двух самостоятельных композициях: portrait и 16:9. +- `source-materials/` — исходное содержательное задание для набора гайдов и шпаргалок. +- `MANIFEST.md` — точный перечень файлов и размеров изображений. + +## Зафиксированный визуальный контракт + +- Канонический ember: `#FF6B35`. +- Доступный ember для обычного текста на светлом фоне: `#C94400`. +- Тёмный холодный фон, тонкие серые линии, плоские поверхности. +- Прямые углы по умолчанию: `radius: 0`. +- Один горячий акцент; зелёный используется только для подтверждённого успеха. +- Моноширинные команды и идентификаторы. +- Без свечения, огненных градиентов, стекла, мягких теней и декоративных скруглений. +- Состояния и типы различаются не только цветом. + +## Финальность отбора + +В пакет включены только последние принятые версии изображений. Исключены промежуточные варианты: + +- с выдуманной монограммой `FP`; +- со служебными бейджами `CHEAT SHEET`, `A4` или `16:9` внутри макета; +- алфавитная A–Z-карта, которую заменила группировка по рабочим сценариям; +- браузерные HTML-рендеры серии, от которых отказались в пользу растровой инфографики. + +## Использование + +- Для разработки интерфейса начать с `design-system/tokens.css`, `design-system/tokens.json` и `design-system/components.html`. +- Для инженерных правил и миграции открыть `design-system/DESIGN-SYSTEM.ru.md` или английскую версию. +- Для публикаций и презентаций использовать изображения из `visual-guides/` и `command-map/`. +- Для печати использовать portrait-карту команд либо HTML-шпаргалки с печатными стилями. + diff --git a/design/command-map/forgeplan-command-map-16x9.png b/design/command-map/forgeplan-command-map-16x9.png new file mode 100644 index 00000000..7d3d2e1f Binary files /dev/null and b/design/command-map/forgeplan-command-map-16x9.png differ diff --git a/design/command-map/forgeplan-command-map-a4-portrait.png b/design/command-map/forgeplan-command-map-a4-portrait.png new file mode 100644 index 00000000..0d3ca332 Binary files /dev/null and b/design/command-map/forgeplan-command-map-a4-portrait.png differ diff --git a/design/forgeplan-design-system/DESIGN-SYSTEM.en.md b/design/forgeplan-design-system/DESIGN-SYSTEM.en.md new file mode 100644 index 00000000..c821d44e --- /dev/null +++ b/design/forgeplan-design-system/DESIGN-SYSTEM.en.md @@ -0,0 +1,296 @@ +# ForgePlan Design System + +Version 1.1 · 14 August 2026 +Labels: **fact** — present in production code; **proposal** — a completed gap; **deprecated** — scheduled for migration. + +## 0. Decisions and inconsistencies + +1. **The canonical accent is `#FF6B35` (`--forge-ember`).** It is defined in `global.css`, the documentation theme and Tailwind tokens. Its contrast on `#0D0D0D` is `6.85:1`; the blog’s `#FF5A1F` reaches `6.23:1`. `--accent: #FF5A1F` is deprecated. +2. Neither orange works as normal text on the light background: `2.59:1` and `2.85:1`. **Proposal:** use `--forge-ember-text: #C94400` for light-theme text and links (`4.60:1` on `#F5F5F0`). Keep base ember for fills, borders, large graphics and focus rings. +3. **The blog diverges from the contract:** separate `#050505/#FFFFFF` backgrounds, a separate neutral scale, `6px` cards/code blocks and extra accent colours. Treat this as migration debt, not as a second design system. +4. **Radii are normalized.** `0` by default; `2px` for compact labels and micro-controls; `3px` only for inline-code backgrounds; `50%` for avatars and status dots. Remove `4px` and `6px` from shared components. +5. `--header-h` is a state contract: `88px` expanded and `36px` compact. + +### Accent migration + +1. Add `--forge-ember`, `--forge-ember-text` and `--forge-ember-soft` to the shared token layer. +2. Replace `var(--accent)` by role: text/link → `var(--forge-ember-text)`; fill/border/indicator → `var(--forge-ember)`. +3. Replace `#ff5a1f` literals and fallbacks in `blog-theme.css`. +4. Remove `--accent` after one release cycle. A temporary `--accent: var(--forge-ember)` alias is acceptable. +5. Gate with `rg -n '#ff5a1f|--accent\\b' website/src`. + +## 1. Foundations + +### 1.1 Palette + +| Token | Dark | Light | Purpose | Status | +|---|---:|---:|---|---| +| `--forge-bg` | `#0D0D0D` | `#F5F5F0` | page background | fact | +| `--forge-fg` | `#E8E8E8` | `#1A1A1A` | primary text | fact | +| `--forge-surface` | `#161616` | `#FFFFFF` | raised surface | fact | +| `--forge-line` | `#3A3A3A` | `#D4D4D0` | border/divider | fact | +| `--forge-dim` | `#949494` | `#6B6B6B` | secondary text | fact | +| `--forge-ember` | `#FF6B35` | `#FF6B35` | accent; not body text in light | fact | +| `--forge-ember-text` | `#FF6B35` | `#C94400` | accessible accent text | proposal | +| `--forge-green` | `#28C840` | `#28C840` | source success hue | fact | +| `--forge-error` | `#EF4444` | `#EF4444` | source error hue | fact | +| `--forge-warning` | `#F59E0B` | `#F59E0B` | warning | proposal | +| `--forge-info` | `#60A5FA` | `#60A5FA` | information | proposal | + +Semantic colours are not secondary brand accents. They appear only in status context and always have a word or glyph. + +### 1.2 Contrast + +WCAG thresholds: normal text `≥4.5:1`, large text `≥3:1`; control boundaries and states `≥3:1` against adjacent colours. + +| Foreground | Dark bg | Dark surface | Light bg | Light surface | Result | +|---|---:|---:|---:|---:|---| +| theme primary text | 15.86 | 14.77 | 15.91 | 17.40 | AA/AAA | +| theme `dim` | 6.41 | 5.97 | 4.87 | 5.33 | AA | +| theme `line` | 1.71 | 1.59 | 1.36 | 1.49 | divider only; insufficient alone for controls | +| `ember #FF6B35` | 6.85 | 6.38 | 2.59 | 2.84 | text in dark only | +| legacy `#FF5A1F` | 6.23 | 5.80 | 2.85 | 3.12 | still fails light; deprecated | +| `green #28C840` | 8.72 | 8.12 | 2.04 | 2.23 | light text needs `#166534` | +| `error #EF4444` | 5.16 | 4.81 | 3.44 | 3.76 | light text needs `#991B1B` | +| `warning #F59E0B` | 9.05 | 8.43 | 1.96 | 2.15 | light text needs `#92400E` | + +`#1A1A1A` on ember is `6.14:1`; white on ember is `2.84:1`. Primary buttons therefore use dark labels. `line` is valid for structure, but hover/control boundaries must strengthen to `dim` or ember. + +### 1.3 Type + +- `Space Grotesk`: headings, UI and prose. +- `Geist Mono`: commands, code, identifiers, reliability values and metadata. +- Body: `16px/1.55`; docs max `72ch`; blog `18px/1.7`, max `68ch`. +- Heading weight `500–600`; avoid decorative extra-bold display type. + +| Token | px | Status | Use | +|---|---:|---|---| +| `xs` | 12 | proposal | metadata | +| `sm` | 14 | fact | compact UI | +| `base` | 16 | fact | body | +| `lg` | 18 | fact | lead/blog | +| `xl` | 20 | proposal | H4/card title | +| `2xl` | 24 | fact | H3 | +| `3xl` | 32 | fact | H2 | +| `4xl` | 40 | fact | document H1 | +| `5xl` | 48 | proposal | page H1 | +| `6xl` | 64 | proposal | landing hero only | + +### 1.4 Rhythm and layout + +**Proposal:** `0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96px`. Every value sits on a 4px base; major composition steps use 8px multiples. + +- `4–8`: compact label interiors. +- `12–16`: controls and dense rows. +- `20–24`: cards and component sections. +- `32`: fixed desktop gutter; `1280 − 2×32 = 1216px` usable width. +- `48–64`: documentation sections. +- `80–96`: landing sections. +- Below `720px`, the gutter may become `20px` (**proposal**) while all surfaces keep a shared edge. + +### 1.5 Borders, radii and height + +Use `1px solid var(--forge-line)` for elevation, never a soft shadow. Avoid doubled nested borders. Zero-radius geometry is the baseline. + +| Radius | Allowed use | +|---:|---| +| `0` | buttons, fields, cards, tables, blocks, dialogs | +| `2px` | compact label inside a dense row | +| `3px` | inline-code background | +| `50%` | avatar, status dot, spinner | + +## 2. Components + +### 2.1 Buttons + +Every target is at least `44×44px`. `sm` keeps a 44px target while reducing type and horizontal padding; `md` is 44px; `lg` is 48px. + +| Variant | Purpose | Rest | Hover/pressed | +|---|---|---|---| +| primary | the one main action | ember + `#1A1A1A` | brightness +8% / −8%, 1px shift | +| secondary | routine action | surface + line | strengthen border to `dim` | +| ghost | low-priority toolbar action | no border | reveal `line` | +| danger | destructive action | transparent + error border/text | subtle error background | + +States: `focus-visible` uses a double `2px ember + 2px background` ring; disabled uses opacity `0.48` and no hover; loading keeps its label, adds a spinner, sets `aria-busy="true"` and blocks repeated activation. Icon-only controls require a familiar symbol and an `aria-label`. + +### 2.2 Fields + +Minimum 44px high, `10×12` padding, mono for technical input. Hover strengthens to `dim`; focus uses ember. Error requires message text, `aria-invalid` and a `!` glyph. Placeholder never replaces label. Distinguish disabled from read-only: disabled is faded; read-only remains legible and carries `READ ONLY`. + +### 2.3 Cards + +A card groups one entity. Surface + 1px line, 20/24px padding, radius 0. Do not turn every section into a card. An interactive card gets a border hover and one visible text action; its full hit area must have an accessible name. + +### 2.4 Tables + +| Density | Cell V×H | Type | Use | +|---|---:|---:|---| +| regular | 12×16 | 14 | docs, short comparisons | +| dense | 8×12 | 14 | artifact lists | +| ultra-dense | 4×8 | 12 mono | cheat sheets, logs | + +Headers are sticky and opaque. Zebra uses at most a 3% foreground tint and only in wide tables. Row hover cannot be the only selection cue. Numbers align right in mono; identifiers align left in mono. Narrow screens scroll horizontally with a visible boundary; never shrink below 12px. Sorting uses label + arrow + `aria-sort`. Printed rows do not split. + +### 2.5 Code + +- Inline: mono 13px, `ember-text`, 14% ember background, 3px radius. +- Command: a visually separate `$`; copy without `$`. +- Output: `dim`, no `$`; failures include `ERROR`/`×`, not colour alone. +- Block: surface, line, radius 0, 16/20px padding, `overflow-x:auto`, `white-space:pre`. +- Copy target ≥44px with a text label; switch to `Copied` for two seconds. +- Do not wrap commands by default; prose code may use `overflow-wrap:anywhere`. + +### 2.6 Alerts + +All alerts use a 3px left border, glyph and explicit title: `i INFO`, `✓ SUCCESS`, `! WARNING`, `× DANGER`. The body background stays neutral. Coloured text uses accessible `*-text` tokens. Alerts do not replace inline field errors. Dynamic results use `role=status`; critical failures use `role=alert`. + +### 2.7 Artifact types + +**Proposal:** one `[glyph] Label` badge, mono, neutral border: + +`P PRD`, `R RFC`, `A ADR`, `S Spec`, `E Epic`, `V Evidence`, `! Problem`, `✓ Solution`, `N Note`, `↻ Refresh`. + +Colour may be a secondary channel, but name and glyph remain. Ten saturated type colours would violate the single-accent rule. + +### 2.8 Reliability 0.0–1.0 + +**Proposal:** combine value, named band and segmented bar: + +- `0.00–0.24 LOW` +- `0.25–0.49 LIMITED` +- `0.50–0.74 MODERATE` +- `0.75–0.89 HIGH` +- `0.90–1.00 PROVEN` +- `— NOT RUN`: empty hatched bar, never `0.00`. + +Use mono with two decimals. Never rely on a red-to-green ramp. `0.00` means a calculated zero; `—` means no calculation. + +## 3. Composition + +1. One `max-width:1280px; padding-inline:32px` container. +2. Header, sidebar, main content and footer share vertical edges. +3. Build density with tables, rules and type—not floating card clouds. +4. One primary per visible task. Everything else is secondary/ghost. +5. One hot spot per composition; ember does not colour every heading. +6. Sticky elements use `top:var(--header-h)`. +7. The header may animate `88→36px`; reduced motion switches state without intermediate frames. + +## 4. Accessibility + +- Apply contrast by role, not hex alone. Base status hues cannot be normal light-theme text. +- Never remove the global `:focus-visible` on hover. Recommended: `outline:2px solid ember; outline-offset:2px; box-shadow:0 0 0 4px bg`. +- Minimum target 44×44; the glyph inside may be smaller. +- Type/status/reliability uses word + glyph + optional colour. +- Tables need a caption or accessible name; sorting needs `aria-sort`. +- Loading announces text and `aria-busy`. +- `prefers-reduced-motion:reduce` reduces transitions/animations to `0.01ms`, removes smooth scroll and parallax. +- Skip link is the first focusable control. +- At 200% zoom, the page itself does not scroll horizontally; code/table regions may. + +## 5. Print + +```css +@media print { + :root,[data-theme]{--forge-bg:#fff;--forge-fg:#111;--forge-surface:#fff; + --forge-line:#777;--forge-dim:#444;--forge-ember-text:#8A2F0B} + *{box-shadow:none!important;text-shadow:none!important} + body{background:#fff!important;color:#111!important;font-size:10pt} + nav,.no-print,button{display:none!important} + a[href^="http"]::after{content:" (" attr(href) ")";font:8pt var(--forge-font-mono)} + table{display:table;width:100%} thead{display:table-header-group} + tr,pre,.card,.alert{break-inside:avoid} + pre{white-space:pre-wrap;overflow-wrap:anywhere} + @page{size:A4;margin:12mm} +} +``` + +Do not print the dot grid. Remove coloured fills but keep borders. Do not expose internal-anchor URLs. Repeat table headers on every page. + +## 6. Surfaces + +| Surface | Changes | Remains fixed | +|---|---|---| +| landing | 5xl/6xl, 80–96px sections, optional dot grid | palette, shared edge, one ember, sharp corners | +| docs | 16px body, 72ch, TOC, code-heavy | tokens, focus, tables, `header-h` | +| blog | 18/1.7, 68ch, longer rhythm | theme background, ember, type, radius 0 | +| cheat sheet | ultra-dense, 12px, A4 | distinguishability, borders, tokens | +| GitHub README | GitHub system fonts, limited CSS | terminology, order, no emoji-only meaning | +| slides | 32–64px, less detail, 16:9 | colour contract, mono IDs/commands, one accent | + +README cannot literally reproduce the theme. Use SVG/PNG from `favicon_pack`, Markdown tables, fenced code and short status labels. Do not rely on custom properties. + +## 7. Do not + +- fire gradients, glow, sparks, glass or soft shadows; +- default rounding or blog `6px` in new shared components; +- pure white as the light page background; +- `#FF5A1F` in new code; +- orange body text on the light theme; +- white text on ember buttons; +- colour without a word/glyph; +- ambiguous icon without a label; +- multiple primaries in one task; +- sticky `top:88px` instead of `var(--header-h)`; +- motion without `prefers-reduced-motion`; +- `line` as the only focus indicator. + +## 8. Unified system: modules and consumers (v1.1) + +The system is single across every ForgePlan surface and ships as modules: + +| Module | File | Contents | Provenance | +|---|---|---|---| +| Base | `tokens.css` | palette, typography, rhythm, radii, layout | site audit 2026-07-25 | +| Neutral steps | `tokens.css` (v1.1 block) | `dim-2`, `dim-3`, `surface-2`, `scrim`, `overlay`, `on-ember` | ported from forgeplan-web, rebased on the canon | +| Graph/map | `tokens.graph.css` | relation edges, canvas strokes, nodes, composed-map zones, dot-grid | ported from forgeplan-web (production @forgeplan/web) | + +Best-of merge rules: + +1. **The canonical base always wins**: backgrounds `#0D0D0D/#F5F5F0`, ember `#FF6B35`, Space Grotesk + Geist Mono, radius 0, no shadows. forgeplan-web's shadows (`--shadow-card`) and fonts (Inter/JetBrains Mono) were **not** taken. +2. **The edge palette is not a second accent.** It is a data-viz channel for relation kinds (`informs`/`refines`/`contains`/`supersedes`), lives only inside graph scenes, and never appears in regular UI. +3. **The `orch` theme** (pure black + lavender) stays a forgeplan-web private theme, outside the canon. +4. Neutral steps were added because dense graph scenes need more than two levels (`fg`/`dim`); values are contrast-aligned to the canonical backgrounds. + +Everything rejected is recorded visually: the `DS / X · Not taken` frame in `design/forgeplan-site.pen` holds a specimen of every not-taken decision with an explanation — the legacy accent, `#050505`, Inter/JetBrains Mono, shadows, 6px radii, the `orch` theme, white text on ember. + +### Consumers + +| Consumer | Status | Action | +|---|---|---| +| `website/` landing + docs | canonical | none | +| `website/` blog-theme | debt: `#FF5A1F`, `#050505`, 6px radii | migrate per §0 | +| `forgeplan-web` (`@forgeplan/web`) | debt: legacy accent, own fonts, shadows | mapping below | +| Pencil (`design/forgeplan-site.pen`) | canonical: `canon-*` variables, atomic layers | CANVAS source | + +### forgeplan-web migration mapping + +| Was (app.css) | Becomes | +|---|---| +| `--accent #ff5a1f` | `--forge-ember` (fill/border) / `--forge-ember-text` (text) | +| `--bg #050505`, `--bg-1..3` | `--forge-bg`, `--forge-surface`, `--forge-surface-2` | +| `--fg-1..4` | `--forge-fg`, `--forge-dim`, `--forge-dim-2`, `--forge-dim-3` | +| `--line-1..3` | `--forge-line` (+ `dim` for emphasis) | +| `--font-sans Inter`, `--font-mono JetBrains Mono` | `--forge-font-sans`, `--forge-font-mono` | +| `--shadow-*` | drop: flatness via 1px borders | +| `--on-accent` (light: `#fff`) | `--forge-on-ember #1A1A1A` — dark label always | +| `--edge-*`, `--canvas-*`, `--map-*`, dot-grid | `tokens.graph.css` (same roles, `--forge-` prefix) | +| `orch` theme | stays app-specific on top of the base | + +## 9. Contract + +The executable reference is `components.html`; CSS contract is `tokens.css`; machine-readable contract is `tokens.json`; A4 references are `cheatsheet.*.html`. + +```html + + +``` + +```css +.component { + color: var(--forge-fg); + background: var(--forge-surface); + border: 1px solid var(--forge-line); + border-radius: var(--forge-radius-0); +} +``` diff --git a/design/forgeplan-design-system/DESIGN-SYSTEM.ru.md b/design/forgeplan-design-system/DESIGN-SYSTEM.ru.md new file mode 100644 index 00000000..c0d8d6e6 --- /dev/null +++ b/design/forgeplan-design-system/DESIGN-SYSTEM.ru.md @@ -0,0 +1,299 @@ +# ForgePlan Design System + +Версия 1.1 · 14 августа 2026 +Статусы: **факт** — найдено в рабочем коде; **предложение** — достроенная часть системы; **перенос v1.1** — забрано из forgeplan-web и пересажено на канон; **устарело** — подлежит миграции. + +## 0. Решения и найденные противоречия + +1. **Канонический акцент — `#FF6B35` (`--forge-ember`).** Он определён в `global.css`, теме документации и Tailwind-токенах. На `#0D0D0D` контраст `6.85:1`; у блогового `#FF5A1F` — `6.23:1`. `--accent: #FF5A1F` объявляется устаревшим. +2. На светлом фоне ни один из двух оранжевых не годится для обычного текста: `2.59:1` и `2.85:1`. **Предложение:** `--forge-ember-text: #C94400` для текста и ссылок в светлой теме (`4.60:1` на `#F5F5F0`). `--forge-ember` остаётся цветом заливки, границы, крупной графики и кольца фокуса. +3. **Блог расходится с каноном:** отдельные фоны `#050505/#FFFFFF`, отдельная нейтральная шкала, `6px` на карточках и блоках кода, дополнительные акцентные цвета. Это технический долг. Общая система не наследует эти значения. +4. **Скругления нормализуются.** `0` — по умолчанию; `2px` — компактные метки/микроэлементы; `3px` — только фон строчного кода; `50%` — аватары и точки состояния. `4px` и `6px` вывести из общих компонентов. +5. `--header-h` — контракт состояния, а не декоративная переменная: `88px` в полном и `36px` в компактном состоянии. + +### Миграция акцента + +1. Добавить `--forge-ember`, `--forge-ember-text`, `--forge-ember-soft` в общий слой токенов. +2. Заменять `var(--accent)` по роли: текст/ссылка → `var(--forge-ember-text)`; фон/граница/индикатор → `var(--forge-ember)`. +3. Заменить `#ff5a1f` и fallback `#ff5a1f` в `blog-theme.css`. +4. Удалить `--accent` после одного релизного цикла. Временно допустим `--accent: var(--forge-ember)`. +5. Добавить проверку: `rg -n '#ff5a1f|--accent\\b' website/src`. + +## 1. Основа + +### 1.1 Палитра + +| Токен | Тёмная | Светлая | Назначение | Статус | +|---|---:|---:|---|---| +| `--forge-bg` | `#0D0D0D` | `#F5F5F0` | фон страницы | факт | +| `--forge-fg` | `#E8E8E8` | `#1A1A1A` | основной текст | факт | +| `--forge-surface` | `#161616` | `#FFFFFF` | приподнятая поверхность | факт | +| `--forge-line` | `#3A3A3A` | `#D4D4D0` | граница и разделитель | факт | +| `--forge-dim` | `#949494` | `#6B6B6B` | вторичный текст | факт | +| `--forge-ember` | `#FF6B35` | `#FF6B35` | акцент без обычного текста в light | факт | +| `--forge-ember-text` | `#FF6B35` | `#C94400` | доступный акцентный текст | предложение | +| `--forge-green` | `#28C840` | `#28C840` | исходный цвет успеха | факт | +| `--forge-error` | `#EF4444` | `#EF4444` | исходный цвет ошибки | факт | +| `--forge-warning` | `#F59E0B` | `#F59E0B` | предупреждение | предложение | +| `--forge-info` | `#60A5FA` | `#60A5FA` | информация | предложение | + +Семантический цвет не становится вторым брендовым акцентом: он появляется только рядом со статусом и всегда сопровождается словом/знаком. + +### 1.2 Контраст + +WCAG: обычный текст `≥4.5:1`, крупный `≥3:1`; границы и состояния элементов управления `≥3:1` относительно соседнего цвета. + +| Передний план | На dark bg | На dark surface | На light bg | На light surface | Вывод | +|---|---:|---:|---:|---:|---| +| основной текст темы | 15.86 | 14.77 | 15.91 | 17.40 | AA/AAA | +| `dim` темы | 6.41 | 5.97 | 4.87 | 5.33 | AA | +| `line` темы | 1.71 | 1.59 | 1.36 | 1.49 | только разделитель; не граница контрола без усиления | +| `ember #FF6B35` | 6.85 | 6.38 | 2.59 | 2.84 | текст только dark; light — заливка/графика | +| legacy `#FF5A1F` | 6.23 | 5.80 | 2.85 | 3.12 | не решает light; устарело | +| `green #28C840` | 8.72 | 8.12 | 2.04 | 2.23 | light-тексту нужен `#166534` | +| `error #EF4444` | 5.16 | 4.81 | 3.44 | 3.76 | light-тексту нужен `#991B1B` | +| `warning #F59E0B` | 9.05 | 8.43 | 1.96 | 2.15 | light-тексту нужен `#92400E` | + +Дополнительно: тёмный `#1A1A1A` на заливке `#FF6B35` = `6.14:1`; белый на той же заливке = `2.84:1`. Поэтому основная кнопка всегда с тёмной подписью. `--forge-line` допустим для структурных линий, но фокус и границы интерактивных элементов при наведении должны усиливаться `dim`/`ember`. + +### 1.3 Типографика + +- `Space Grotesk` — заголовки, интерфейс и длинный текст. +- `Geist Mono` — команды, код, идентификаторы, числа надёжности, метаданные. +- Основной текст: `16px/1.55`; документация: максимум `72ch`; блог: `18px/1.7`, максимум `68ch`. +- Вес заголовков `500–600`; не использовать декоративный сверхжирный набор. + +| Токен | Размер | Статус | Применение | +|---|---:|---|---| +| `xs` | 12 | предложение | метаданные | +| `sm` | 14 | факт | компактный интерфейс | +| `base` | 16 | факт | основной текст | +| `lg` | 18 | факт | лид/блог | +| `xl` | 20 | предложение | H4/карточка | +| `2xl` | 24 | факт | H3 | +| `3xl` | 32 | факт | H2 | +| `4xl` | 40 | факт | H1 документа | +| `5xl` | 48 | предложение | H1 страницы | +| `6xl` | 64 | предложение | hero, только лендинг | + +### 1.4 Ритм и макет + +**Предложение:** шкала `0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96px`. Число — кратность `4px`; основные композиционные шаги кратны `8px`. + +- `4–8`: внутри компактной метки. +- `12–16`: контролы и плотные строки. +- `20–24`: карточки и секции компонентов. +- `32`: обязательный desktop gutter; `1280 − 2×32 = 1216px` полезной ширины. +- `48–64`: разделы документации. +- `80–96`: крупные секции лендинга. +- До `720px` gutter может стать `20px` (**предложение**), но все поверхности продолжают иметь общий край. + +### 1.5 Границы, скругления, высота + +Плоскость задаётся `1px solid var(--forge-line)`, не тенью. Вложенные границы не дублировать. Нулевая геометрия — базовая. Исключения нужны для функции, не для «мягкости». + +| Радиус | Допустимо | +|---:|---| +| `0` | кнопки, поля, карточки, таблицы, блоки, диалоги | +| `2px` | компактная метка внутри плотной строки | +| `3px` | подложка строчного кода | +| `50%` | аватар, точка состояния, спиннер | + +## 2. Элементы + +### 2.1 Кнопки + +Общая цель — минимум `44×44px`. `sm` сохраняет высоту 44, но уменьшает текст/горизонтальный отступ; `md` — 44; `lg` — 48. + +| Вид | Назначение | Покой | Hover/pressed | +|---|---|---|---| +| primary | одно главное действие экрана | ember + `#1A1A1A` | яркость +8% / −8%, смещение 1px | +| secondary | обычные действия | surface + line | граница `dim` | +| ghost | низкий приоритет в панели | без границы | появляется `line` | +| danger | разрушительное действие | прозрачная + error border/text | лёгкая error-подложка | + +Состояния: `focus-visible` — двойное кольцо `2px ember + 2px фон`; `disabled` — opacity `0.48`, без hover; `loading` — подпись остаётся, слева спиннер, `aria-busy="true"`, повторное нажатие блокируется. Иконка без подписи допустима только для общеизвестного действия и обязана иметь `aria-label`. + +### 2.2 Поля + +Высота ≥44px, padding `10×12`, mono для технического ввода. Hover усиливает границу до `dim`; focus — ember; ошибка включает текст, `aria-invalid`, значок `!` и сообщение. Placeholder не заменяет label. Disabled и read-only различать: disabled бледный, read-only обычный с меткой `READ ONLY`. + +### 2.3 Карточки + +Карточка группирует одну сущность. Surface + 1px line, padding 20/24, радиус 0. Не превращать каждую секцию в карточку. Интерактивная карточка получает hover по границе и одно видимое текстовое действие; вся кликабельная область должна иметь доступное имя. + +### 2.4 Таблицы + +| Плотность | Ячейка V×H | Текст | Где | +|---|---:|---:|---| +| обычная | 12×16 | 14 | документация, короткие сравнения | +| плотная | 8×12 | 14 | списки записей | +| очень плотная | 4×8 | 12 mono | шпаргалки, логи | + +Шапка липкая, непрозрачная. Zebra — максимум 3% примеси foreground и только для широких таблиц. Hover строки не может быть единственным указателем выбора. Числа выравнивать вправо и mono; идентификаторы — влево и mono. На узком экране — горизонтальный scroll с видимым краем; не уменьшать текст ниже 12px. Сортировка: слово + стрелка + `aria-sort`. Не разрывать строки при печати. + +### 2.5 Код + +- Строчный код: mono 13px, `ember-text`, 14% ember-подложка, радиус 3px. +- Команда: строка начинается с визуально отдельного `$`; копируется без `$`. +- Вывод: `dim`, без `$`; ошибки содержат `ERROR`/`×`, не только красный. +- Блок: surface, line, radius 0, padding 16/20, `overflow-x:auto`, `white-space:pre`. +- Кнопка копирования ≥44px, текстовая; после успеха пишет `Скопировано` и возвращается через 2 секунды. +- Длинные команды не переносятся по умолчанию; для prose-кода допускается `overflow-wrap:anywhere`. + +### 2.6 Оповещения + +Все имеют левую границу 3px, знак и явный заголовок: `i INFO`, `✓ SUCCESS`, `! WARNING`, `× DANGER`. Фон остаётся нейтральным. Цветной текст использует доступный `*-text`. Оповещение не заменяет ошибку рядом с полем. Для динамического результата: `role=status`; для критической ошибки: `role=alert`. + +### 2.7 Типы записей + +**Предложение:** единая метка `[глиф] Название`, mono, нейтральная рамка. Глиф обязателен: + +`P PRD`, `R RFC`, `A ADR`, `S Spec`, `E Epic`, `V Evidence`, `! Problem`, `✓ Solution`, `N Note`, `↻ Refresh`. + +Цвет можно добавить как вторичный канал, но название и глиф всегда остаются. Не использовать десять самостоятельных насыщенных цветов: это разрушит правило одного акцента. + +### 2.8 Надёжность 0.0–1.0 + +**Предложение:** сочетание числа, словесного диапазона и сегментированной шкалы: + +- `0.00–0.24 LOW` +- `0.25–0.49 LIMITED` +- `0.50–0.74 MODERATE` +- `0.75–0.89 HIGH` +- `0.90–1.00 PROVEN` +- `— NOT RUN` — штрихованная пустая шкала, никогда `0.00`. + +Число всегда mono с двумя знаками. Не кодировать качество только красно-зелёной шкалой. `0.00` означает рассчитанный нулевой результат; `—` означает отсутствие расчёта. + +## 3. Композиция + +1. Один контейнер `max-width:1280px; padding-inline:32px`. +2. Заголовок, боковая панель, основной блок и подвал имеют общий вертикальный край. +3. Информационная плотность строится таблицами, линиями и типографикой, не набором плавающих карточек. +4. Один primary на видимую задачу. Остальные действия secondary/ghost. +5. Один hot spot на композицию: ember не размазывается по каждому заголовку. +6. Липкие элементы используют `top:var(--header-h)`. +7. Анимация шапки может идти `88→36px`; при reduced motion состояние меняется без промежуточных кадров. + +## 4. Доступность + +- Контраст применять по роли, а не только по hex. Исходные status hues в light нельзя использовать как обычный текст. +- Глобальный `:focus-visible` не удаляется на hover. Рекомендуемая форма: `outline:2px solid ember; outline-offset:2px; box-shadow:0 0 0 4px bg`. +- Минимальная цель 44×44; визуальная иконка может быть меньше внутри неё. +- Тип/статус/надёжность: слово + глиф + при необходимости цвет. +- У каждой таблицы есть caption или доступное имя, у сортировки — `aria-sort`. +- Состояние загрузки сообщает текст и `aria-busy`. +- `prefers-reduced-motion:reduce` сводит transition/animation к `0.01ms`, отключает smooth scroll и параллакс. +- Skip link — первый фокусируемый элемент. +- Масштаб 200% не создаёт горизонтального scroll страницы; scroll разрешён внутри таблицы/кода. + +## 5. Печать + +```css +@media print { + :root,[data-theme]{--forge-bg:#fff;--forge-fg:#111;--forge-surface:#fff; + --forge-line:#777;--forge-dim:#444;--forge-ember-text:#8A2F0B} + *{box-shadow:none!important;text-shadow:none!important} + body{background:#fff!important;color:#111!important;font-size:10pt} + nav,.no-print,button{display:none!important} + a[href^="http"]::after{content:" (" attr(href) ")";font:8pt var(--forge-font-mono)} + table{display:table;width:100%} thead{display:table-header-group} + tr,pre,.card,.alert{break-inside:avoid} + pre{white-space:pre-wrap;overflow-wrap:anywhere} + @page{size:A4;margin:12mm} +} +``` + +Не печатать декоративную dot-grid. Цветные заливки убирать, границы сохранять. Для внутренних якорей URL не раскрывать. Заголовок таблицы повторять на каждой странице. + +## 6. Поверхности + +| Поверхность | Меняется | Не меняется | +|---|---|---| +| лендинг | 5xl/6xl, секции 80–96, допустима dot-grid | палитра, общий край, один ember, прямые углы | +| документация | текст 16, 72ch, TOC, code-heavy | токены, focus, таблицы, `header-h` | +| блог | текст 18/1.7, 68ch, более длинный ритм | фон темы, ember, типографика, radius 0 | +| шпаргалка | ultra-dense, 12px, A4 | различимость, границы, токены | +| GitHub README | системные шрифты GitHub, ограниченный CSS | терминология, порядок, emoji не заменяют глифы | +| слайды | 32–64px, меньше деталей, 16:9 | цветовой контракт, mono для ID/команд, один акцент | + +README не может буквально воспроизвести тему: использовать SVG/PNG из `favicon_pack`, таблицы Markdown, fenced code и короткие статусы. Не вставлять HTML, зависящий от CSS-переменных. + +## 7. Чего не делать + +- огонь, glow, искры, стекло, мягкие тени; +- радиус по умолчанию и блоговые `6px` в новых компонентах; +- чистый белый как фон light; +- `#FF5A1F` в новом коде; +- оранжевый обычный текст на светлом фоне; +- белый текст на ember-кнопке; +- цвет без слова/глифа; +- иконка без подписи при неочевидном значении; +- несколько primary в одной задаче; +- sticky `top:88px` вместо `var(--header-h)`; +- transition без `prefers-reduced-motion`; +- граница `line` как единственный индикатор фокуса. + +## 8. Единая система: модули и потребители (v1.1) + +Система едина для всех поверхностей ForgePlan и состоит из модулей: + +| Модуль | Файл | Что внутри | Происхождение | +|---|---|---|---| +| База | `tokens.css` | палитра, типографика, ритм, радиусы, layout | аудит сайта 25.07.2026 | +| Ступени нейтральных | `tokens.css` (блок v1.1) | `dim-2`, `dim-3`, `surface-2`, `scrim`, `overlay`, `on-ember` | перенос из forgeplan-web, цвета пересажены на канон | +| Граф/карта | `tokens.graph.css` | рёбра связей, штрихи канвы, узлы, зоны composed-map, dot-grid | перенос из forgeplan-web (боевой код @forgeplan/web) | + +Правила слияния «забираем лучшее»: + +1. **База канона побеждает всегда**: фоны `#0D0D0D/#F5F5F0`, ember `#FF6B35`, Space Grotesk + Geist Mono, radius 0, без теней. Тени forgeplan-web (`--shadow-card`) и его шрифты (Inter/JetBrains Mono) в единую систему **не забраны**. +2. **Палитра рёбер графа — не второй акцент.** Это data-viz-канал для типов связей (`informs`/`refines`/`contains`/`supersedes`), он существует только внутри графовых сцен и не появляется в обычном UI. +3. **Тема `orch`** (чёрный + лаванда) остаётся приватной темой forgeplan-web и в канон не входит. +4. Нейтральные ступени добавлены потому, что плотным графовым сценам двух уровней (`fg`/`dim`) мало; значения выровнены по контрасту с каноническими фонами. + +Всё отклонённое зафиксировано визуально: фрейм `DS / X · Not taken` в `design/forgeplan-site.pen` держит образцы каждого не-взятого решения с пояснением — легаси-акцент, `#050505`, Inter/JetBrains Mono, тени, 6px, тема `orch`, белый текст на ember. + +### Потребители и их статус + +| Потребитель | Статус | Что делать | +|---|---|---| +| `website/` лендинг + доки | канон | ничего | +| `website/` blog-theme | долг: `#FF5A1F`, `#050505`, радиусы 6px | миграция по §0 | +| `forgeplan-web` (`@forgeplan/web`) | долг: легаси-акцент, свои шрифты, тени | маппинг ниже | +| Pencil (`design/forgeplan-site.pen`) | канон: переменные `canon-*`, atomic-слои | источник для CANVAS | + +### Маппинг миграции forgeplan-web → единая система + +| Было (app.css) | Стало | +|---|---| +| `--accent #ff5a1f` | `--forge-ember` (заливка/граница) / `--forge-ember-text` (текст) | +| `--bg #050505`, `--bg-1..3` | `--forge-bg`, `--forge-surface`, `--forge-surface-2` | +| `--fg-1..4` | `--forge-fg`, `--forge-dim`, `--forge-dim-2`, `--forge-dim-3` | +| `--line-1..3` | `--forge-line` (+ усиление через `dim`) | +| `--font-sans Inter`, `--font-mono JetBrains Mono` | `--forge-font-sans`, `--forge-font-mono` | +| `--shadow-*` | убрать: плоскость через 1px границы | +| `--on-accent` (light: `#fff`) | `--forge-on-ember #1A1A1A` — тёмная подпись всегда | +| `--edge-*`, `--canvas-*`, `--map-*`, dot-grid | `tokens.graph.css` (те же роли, префикс `--forge-`) | +| тема `orch` | остаётся app-specific поверх базы | + +## 9. Код и контракт + +Полный исполняемый пример находится в `components.html`; CSS-контракт — в `tokens.css`; машинный контракт — в `tokens.json`; A4 — в `cheatsheet.*.html`. + +Минимальное подключение: + +```html + + +``` + +```css +.component { + color: var(--forge-fg); + background: var(--forge-surface); + border: 1px solid var(--forge-line); + border-radius: var(--forge-radius-0); +} +``` + diff --git a/design/forgeplan-design-system/README.md b/design/forgeplan-design-system/README.md new file mode 100644 index 00000000..3c3d7209 --- /dev/null +++ b/design/forgeplan-design-system/README.md @@ -0,0 +1,15 @@ +# ForgePlan Design System package (v1.1 — unified) + +The single design system for every ForgePlan surface (website, forgeplan-web, Pencil, guides, slides). v1.1 merged the best of forgeplan-web into the canon: stepped neutrals + the graph/map token module. See §8 of DESIGN-SYSTEM.*.md for merge rules and consumer migration mappings. + +- `DESIGN-SYSTEM.ru.md` / `DESIGN-SYSTEM.en.md` — canonical documentation. +- `tokens.css` — drop-in CSS custom properties for both themes (base + v1.1 neutral steps). +- `tokens.graph.css` — optional module for graph/map/canvas surfaces (edges, canvas strokes, map zones, dot-grid). Load after tokens.css. +- `tokens.json` — machine-readable token contract with fact/proposal/ported status. +- `components.html` — self-contained bilingual component reference with theme switcher. +- `cheatsheet.ru.html` / `cheatsheet.en.html` — A4 landscape references with print styles. +- `brand-assets/` — logo SVGs, favicons, icons. + +Open the HTML files directly in a browser. No build step or external dependency is required. The declared font stacks fall back to system fonts when Space Grotesk or Geist Mono are not installed. + +Source audit: `website/src/styles/global.css`, `forge-theme.css`, `blog-theme.css`, header/components and the live site, inspected 25 July 2026. diff --git a/design/forgeplan-design-system/brand-assets/README.md b/design/forgeplan-design-system/brand-assets/README.md new file mode 100644 index 00000000..d715d2c2 --- /dev/null +++ b/design/forgeplan-design-system/brand-assets/README.md @@ -0,0 +1,8 @@ +# Brand assets + +Эта папка содержит ассеты из текущего исходного кода сайта ForgePlan. + +- `logo-dark.svg` / `logo-light.svg` — компактный контурный знак. +- `favicon*.svg`, `favicon.ico`, `icon-512.png`, `apple-touch-icon.png` — варианты wireframe cube для браузера и приложений. + +Важно: в части существующих favicon-файлов всё ещё встречается исторический `#FF5A1F`. Дизайн-система фиксирует `#FF6B35` как канонический ember и описывает миграцию в `DESIGN-SYSTEM.ru.md` / `DESIGN-SYSTEM.en.md`. diff --git a/design/forgeplan-design-system/brand-assets/apple-touch-icon.png b/design/forgeplan-design-system/brand-assets/apple-touch-icon.png new file mode 100644 index 00000000..34d207a8 Binary files /dev/null and b/design/forgeplan-design-system/brand-assets/apple-touch-icon.png differ diff --git a/design/forgeplan-design-system/brand-assets/favicon-dark.svg b/design/forgeplan-design-system/brand-assets/favicon-dark.svg new file mode 100644 index 00000000..086c1272 --- /dev/null +++ b/design/forgeplan-design-system/brand-assets/favicon-dark.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + diff --git a/design/forgeplan-design-system/brand-assets/favicon-light.svg b/design/forgeplan-design-system/brand-assets/favicon-light.svg new file mode 100644 index 00000000..d12327a7 --- /dev/null +++ b/design/forgeplan-design-system/brand-assets/favicon-light.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + diff --git a/design/forgeplan-design-system/brand-assets/favicon.ico b/design/forgeplan-design-system/brand-assets/favicon.ico new file mode 100644 index 00000000..1bbe60fe Binary files /dev/null and b/design/forgeplan-design-system/brand-assets/favicon.ico differ diff --git a/design/forgeplan-design-system/brand-assets/favicon.svg b/design/forgeplan-design-system/brand-assets/favicon.svg new file mode 100644 index 00000000..086c1272 --- /dev/null +++ b/design/forgeplan-design-system/brand-assets/favicon.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + diff --git a/design/forgeplan-design-system/brand-assets/icon-512.png b/design/forgeplan-design-system/brand-assets/icon-512.png new file mode 100644 index 00000000..34d207a8 Binary files /dev/null and b/design/forgeplan-design-system/brand-assets/icon-512.png differ diff --git a/design/forgeplan-design-system/brand-assets/logo-dark.svg b/design/forgeplan-design-system/brand-assets/logo-dark.svg new file mode 100644 index 00000000..f1704e15 --- /dev/null +++ b/design/forgeplan-design-system/brand-assets/logo-dark.svg @@ -0,0 +1,3 @@ + + + diff --git a/design/forgeplan-design-system/brand-assets/logo-light.svg b/design/forgeplan-design-system/brand-assets/logo-light.svg new file mode 100644 index 00000000..f1704e15 --- /dev/null +++ b/design/forgeplan-design-system/brand-assets/logo-light.svg @@ -0,0 +1,3 @@ + + + diff --git a/design/forgeplan-design-system/cheatsheet.en.html b/design/forgeplan-design-system/cheatsheet.en.html new file mode 100644 index 00000000..111c0fd5 --- /dev/null +++ b/design/forgeplan-design-system/cheatsheet.en.html @@ -0,0 +1,28 @@ +ForgePlan — design cheat sheet +
+
F●RGEPLAN / DESIGN SYSTEM

Design cheat sheet

A4 · v1.0 · canonical #FF6B35
+

01 / PALETTE

+
bg dark
#0D0D0D
bg light
#F5F5F0
+
fg dark
#E8E8E8
fg light
#1A1A1A
+
surface D
#161616
surface L
#FFFFFF
+
line D
#3A3A3A
line L
#D4D4D0
+
dim D
#949494
dim L
#6B6B6B
+
ember
#FF6B35
ember text L
#C94400
+

Contrast

fg/bg 15.86 · dim/bg 6.41 · ember/dark 6.85
ember/light 2.59 ✕ · dark/ember 6.14 ✓
+

02 / TYPE & RHYTHM

+
xs metadata12
sm interface14
base body16
lg lead18
xl card20
2xl H324
3xl H232
4xl H140
+

Spacing · 4px base

4
8
16
24
32
64
+
Layout 1280 · gutter 32 · content 1216
+

03 / BUTTONS & FOCUS

PRIMARYSECONDARYGHOSTDANGERFOCUSDISABLED
+
  • One primary per task.
  • Target ≥44×44px.
  • Focus: 2px ember + bg.
  • Hover never removes focus.
  • Loading keeps its label.
+

04 / BORDERS

  • 1px line, no shadows.
  • Radius 0 by default.
  • 2px label; 3px inline code.
  • 50% avatar/dot/spinner.
  • Sticky: top:var(--header-h).
+

05 / DENSE DATA

ModeV×Hpx
Regular12×1614
Dense8×1214
Ultra4×812 mono
+

Artifacts

P PRDR RFCA ADRS SpecE EpicV Evidence! Problem✓ SolutionN Note↻ Refresh
+

Reliability

0.00 LOW ≠ — NOT RUN
Value + word + bar; never colour alone.
+

06 / DO NOT

  • Fire, glow, sparks or glass.
  • 4/6px radii or soft shadows.
  • Pure-white light background.
  • #FF5A1F in new code.
  • White labels on ember.
  • Orange body text in light.
  • Colour without word/glyph.
  • Multiple accent colours.
  • Ambiguous unlabeled icon.
  • Motion without reduced mode.
+
Space Grotesk / Geist Mono88px → 36px · --header-hforgeplan.dev
+
diff --git a/design/forgeplan-design-system/cheatsheet.ru.html b/design/forgeplan-design-system/cheatsheet.ru.html new file mode 100644 index 00000000..dba80e1a --- /dev/null +++ b/design/forgeplan-design-system/cheatsheet.ru.html @@ -0,0 +1,28 @@ +ForgePlan — шпаргалка +
+
F●RGEPLAN / DESIGN SYSTEM

Шпаргалка по дизайну

A4 · v1.0 · канон #FF6B35
+

01 / ПАЛИТРА

+
bg dark
#0D0D0D
bg light
#F5F5F0
+
fg dark
#E8E8E8
fg light
#1A1A1A
+
surface D
#161616
surface L
#FFFFFF
+
line D
#3A3A3A
line L
#D4D4D0
+
dim D
#949494
dim L
#6B6B6B
+
ember
#FF6B35
ember text L
#C94400
+

Контраст

fg/bg 15.86 · dim/bg 6.41 · ember/dark 6.85
ember/light 2.59 ✕ · dark/ember 6.14 ✓
+

02 / ТИП И РИТМ

+
xs metadata12
sm interface14
base body16
lg lead18
xl card20
2xl H324
3xl H232
4xl H140
+

Отступы · 4px base

4
8
16
24
32
64
+
Layout 1280 · gutter 32 · content 1216
+

03 / КНОПКИ И ФОКУС

PRIMARYSECONDARYGHOSTDANGERFOCUSDISABLED
+
  • Один primary на задачу.
  • Цель ≥44×44px.
  • Focus: 2px ember + фон.
  • Hover не убирает focus.
  • Loading сохраняет подпись.
+

04 / ГРАНИЦЫ

  • 1px line, без теней.
  • Радиус 0 по умолчанию.
  • 2px — метка; 3px — inline code.
  • 50% — аватар/точка/спиннер.
  • Sticky: top:var(--header-h).
+

05 / ПЛОТНЫЕ ДАННЫЕ

РежимV×Hpx
Обычный12×1614
Плотный8×1214
Очень плотный4×812 mono
+

Записи

P PRDR RFCA ADRS SpecE EpicV Evidence! Problem✓ SolutionN Note↻ Refresh
+

Надёжность

0.00 LOW ≠ — NOT RUN
Число + слово + шкала; не только цвет.
+

06 / НЕ ДЕЛАТЬ

  • Огонь, glow, искры, стекло.
  • Скругления 4/6px и мягкие тени.
  • Чистый белый фон light.
  • #FF5A1F в новом коде.
  • Белый текст на ember.
  • Оранжевый body text в light.
  • Цвет без слова или глифа.
  • Несколько акцентных цветов.
  • Иконка без ясной подписи.
  • Анимация без reduced motion.
+
Space Grotesk / Geist Mono88px → 36px · --header-hforgeplan.dev
+
diff --git a/design/forgeplan-design-system/components.html b/design/forgeplan-design-system/components.html new file mode 100644 index 00000000..948dc904 --- /dev/null +++ b/design/forgeplan-design-system/components.html @@ -0,0 +1,69 @@ + + + + + +ForgePlan — component examples + + + +
+
FORGEPLAN / UI

Примеры компонентовComponent examples

+ +

КнопкиButtons

+
+ +

Поле и карточкаField and card

+
ADR-042 · ACTIVE

Хранилище решений в GitGit-backed decision storage

Решение принято, связано с тремя доказательствами.Decision accepted and linked to three evidence records.

+ +

Плотность таблицTable density

+
+
IDTYPEСОСТОЯНИЕSTATER_eff
PRD-018PRDactive0.82
RFC-003RFCdraft0.44
ADR-001ADRactive—
+ +

Код и терминалCode and terminal

+

Строчная команда:Inline command: forgeplan health

+ 
$ forgeplan health
+Verdict: Healthy
+Artifacts: 341
+Tests: 3084
+ +

ОповещенияAlerts

+
INFO · Индекс обновлён.Index updated.
SUCCESS · Все проверки пройдены.All checks passed.
WARNING · Доказательства устаревают.Evidence is becoming stale.
DANGER · Нарушена связь записей.Artifact link is broken.
+ +

Типы записейArtifact types

+
PPRDRRFCAADRSSpecEEpicVEvidence!Problem✓SolutionNNote↻Refresh
+ +

НадёжностьReliability

+
LOW
0.18 / 1.00
HIGH
0.82 / 1.00
NOT RUN
— / не считаласьnot calculated
+
+ + + diff --git a/design/forgeplan-design-system/tokens.css b/design/forgeplan-design-system/tokens.css new file mode 100644 index 00000000..37edb655 --- /dev/null +++ b/design/forgeplan-design-system/tokens.css @@ -0,0 +1,119 @@ +/* + * ForgePlan design tokens — canonical contract + * Facts preserve the current production palette. Tokens marked PROPOSAL + * complete missing scales and component states. + */ +:root, +[data-theme="dark"] { + color-scheme: dark; + --forge-bg: #0D0D0D; + --forge-fg: #E8E8E8; + --forge-surface: #161616; + --forge-line: #3A3A3A; + --forge-dim: #949494; + --forge-ember: #FF6B35; + --forge-green: #28C840; + --forge-error: #EF4444; + + /* PORTED v1.1 (from forgeplan-web app.css, rebased on the canonical + * palette): stepped neutrals for data-dense UI, overlay plumbing, and + * the accent-contrast contract. */ + --forge-dim-2: #6B6B6B; + --forge-dim-3: #4A4A4A; + --forge-surface-2: #1C1C1C; + --forge-scrim: rgba(0, 0, 0, 0.60); + --forge-overlay: rgba(13, 13, 13, 0.85); + --forge-on-ember: #1A1A1A; + + /* PROPOSAL */ + --forge-ember-text: #FF6B35; + --forge-ember-soft: #FF8A5B; + --forge-success-text: #28C840; + --forge-error-text: #EF4444; + --forge-warning: #F59E0B; + --forge-warning-text: #F59E0B; + --forge-info: #60A5FA; + --forge-info-text: #60A5FA; + --forge-focus-outer: #0D0D0D; + --forge-disabled-opacity: 0.48; +} + +[data-theme="light"] { + color-scheme: light; + --forge-bg: #F5F5F0; + --forge-fg: #1A1A1A; + --forge-surface: #FFFFFF; + --forge-line: #D4D4D0; + --forge-dim: #6B6B6B; + --forge-ember: #FF6B35; + --forge-green: #28C840; + --forge-error: #EF4444; + + /* PORTED v1.1: stepped neutrals + overlays (see dark block). + * --forge-on-ember stays DARK on light too: the primary button label is + * always dark on ember (white fails contrast, 2.84:1). */ + --forge-dim-2: #98938A; + --forge-dim-3: #C4BFB5; + --forge-surface-2: #EFEFE8; + --forge-scrim: rgba(15, 13, 10, 0.42); + --forge-overlay: rgba(245, 245, 240, 0.88); + --forge-on-ember: #1A1A1A; + + /* PROPOSAL: accessible text variants; base semantic hues stay unchanged. */ + --forge-ember-text: #C94400; + --forge-ember-soft: #D94D1B; + --forge-success-text: #166534; + --forge-error-text: #991B1B; + --forge-warning: #F59E0B; + --forge-warning-text: #92400E; + --forge-info: #60A5FA; + --forge-info-text: #1E3A8A; + --forge-focus-outer: #F5F5F0; + --forge-disabled-opacity: 0.48; +} + +:root { + --forge-font-sans: 'Space Grotesk', ui-sans-serif, system-ui, -apple-system, sans-serif; + --forge-font-mono: 'Geist Mono', ui-monospace, SFMono-Regular, Menlo, monospace; + + --forge-text-xs: 0.75rem; /* PROPOSAL: 12px */ + --forge-text-sm: 0.875rem; /* FACT: 14px */ + --forge-text-base: 1rem; /* FACT: 16px */ + --forge-text-lg: 1.125rem; /* FACT: 18px */ + --forge-text-xl: 1.25rem; /* PROPOSAL: 20px */ + --forge-text-2xl: 1.5rem; /* FACT: 24px */ + --forge-text-3xl: 2rem; /* FACT: 32px */ + --forge-text-4xl: 2.5rem; /* FACT: 40px */ + --forge-text-5xl: 3rem; /* PROPOSAL: 48px */ + --forge-text-6xl: 4rem; /* PROPOSAL: 64px */ + + /* PROPOSAL: 4px base with useful 8px milestones. */ + --forge-space-0: 0; + --forge-space-1: 0.25rem; + --forge-space-2: 0.5rem; + --forge-space-3: 0.75rem; + --forge-space-4: 1rem; + --forge-space-5: 1.25rem; + --forge-space-6: 1.5rem; + --forge-space-8: 2rem; + --forge-space-10: 2.5rem; + --forge-space-12: 3rem; + --forge-space-16: 4rem; + --forge-space-20: 5rem; + --forge-space-24: 6rem; + + --forge-radius-0: 0; /* FACT: default */ + --forge-radius-control: 2px; /* PROPOSAL: compact controls/chips only */ + --forge-radius-code: 3px; /* FACT normalized from blog inline code */ + --forge-radius-round: 50%; /* FACT: avatars/status dots only */ + + --forge-border-width: 1px; + --forge-focus-width: 2px; + --forge-target-min: 44px; + --forge-layout-max: 1280px; + --forge-layout-gutter: 32px; + --header-h: 88px; +} + +/* Deprecated. Remove after repository-wide replacement. */ +/* --accent: #FF5A1F; -> use --forge-ember or --forge-ember-text by role. */ diff --git a/design/forgeplan-design-system/tokens.graph.css b/design/forgeplan-design-system/tokens.graph.css new file mode 100644 index 00000000..b2646f3d --- /dev/null +++ b/design/forgeplan-design-system/tokens.graph.css @@ -0,0 +1,91 @@ +/* + * ForgePlan design tokens — GRAPH MODULE (v1.1) + * + * Optional extension for graph / map / canvas surfaces (forgeplan-web + * composed map, DAG explorers, dependency trees). Load AFTER tokens.css. + * + * Provenance: ported from forgeplan-web `template/src/app/styles/app.css` + * (battle-tested in @forgeplan/web), neutrals rebased onto the canonical + * palette (#0D0D0D / #F5F5F0, ink #1A1A1A). Edge hues kept as shipped — + * they are a data-viz palette, distinct from the one-accent brand rule. + * The forgeplan-web "orch" theme is app-specific and NOT part of the canon. + */ +:root, +[data-theme="dark"] { + /* Graph edges (relation palette). */ + --forge-edge-default: rgba(232, 232, 232, 0.85); + --forge-edge-soft: rgba(232, 232, 232, 0.55); + --forge-edge-informs: rgba(232, 232, 232, 0.65); + --forge-edge-refines: rgba(160, 192, 255, 0.65); + --forge-edge-contains: rgba(255, 200, 120, 0.65); + --forge-edge-supersedes: rgba(255, 160, 200, 0.65); + + /* Canvas strokes and labels (SVG scene chrome). */ + --forge-canvas-stroke: rgba(255, 255, 255, 0.45); + --forge-canvas-stroke-2: rgba(255, 255, 255, 0.32); + --forge-canvas-stroke-soft: rgba(255, 255, 255, 0.16); + --forge-canvas-stroke-faint: rgba(255, 255, 255, 0.04); + --forge-canvas-label: rgba(232, 232, 232, 0.78); + --forge-canvas-label-faded: rgba(232, 232, 232, 0.32); + --forge-canvas-label-strong: #FFFFFF; + --forge-canvas-stroke-on-fill: rgba(0, 0, 0, 0.40); + --forge-canvas-overlay: rgba(13, 13, 13, 0.85); + + /* Node defaults. */ + --forge-node-border: rgba(255, 255, 255, 0.70); + --forge-node-fg: #E8E8E8; + + /* Composed-map zone chrome + accent slots. */ + --forge-map-zone: rgba(255, 255, 255, 0.03); + --forge-map-zone-line: rgba(255, 255, 255, 0.14); + --forge-map-clay: #D9785A; + --forge-map-olive: #A8A23C; + --forge-map-accent-cyan: #22B8CF; + --forge-map-accent-emerald: #22C58E; + --forge-map-accent-violet: #A78BFA; + --forge-map-accent-amber: #F0B429; + --forge-map-accent-rose: #FB7185; + --forge-map-accent-orange: #FB8B4C; + --forge-map-accent-slate: #94A3B8; + + /* Dot grid (decorative, never printed). */ + --forge-dot-grid-color: rgba(255, 255, 255, 0.10); + --forge-dot-grid-size: 24px; + --forge-dot-grid-radius: 0.9px; +} + +[data-theme="light"] { + --forge-edge-default: rgba(26, 26, 26, 0.62); + --forge-edge-soft: rgba(26, 26, 26, 0.36); + --forge-edge-informs: rgba(26, 26, 26, 0.45); + --forge-edge-refines: rgba(60, 90, 160, 0.55); + --forge-edge-contains: rgba(170, 110, 30, 0.55); + --forge-edge-supersedes: rgba(180, 60, 110, 0.55); + + --forge-canvas-stroke: rgba(0, 0, 0, 0.45); + --forge-canvas-stroke-2: rgba(0, 0, 0, 0.30); + --forge-canvas-stroke-soft: rgba(0, 0, 0, 0.10); + --forge-canvas-stroke-faint: rgba(0, 0, 0, 0.03); + --forge-canvas-label: rgba(26, 26, 26, 0.85); + --forge-canvas-label-faded: rgba(26, 26, 26, 0.42); + --forge-canvas-label-strong: #1A1A1A; + --forge-canvas-stroke-on-fill: rgba(255, 255, 255, 0.70); + --forge-canvas-overlay: rgba(245, 245, 240, 0.88); + + --forge-node-border: rgba(0, 0, 0, 0.62); + --forge-node-fg: #1A1A1A; + + --forge-map-zone: rgba(0, 0, 0, 0.025); + --forge-map-zone-line: rgba(0, 0, 0, 0.12); + --forge-map-clay: #B8563A; + --forge-map-olive: #6B6B24; + --forge-map-accent-cyan: #0E7490; + --forge-map-accent-emerald: #0F7A56; + --forge-map-accent-violet: #6D28D9; + --forge-map-accent-amber: #92400E; + --forge-map-accent-rose: #BE123C; + --forge-map-accent-orange: #C2410C; + --forge-map-accent-slate: #475569; + + --forge-dot-grid-color: rgba(0, 0, 0, 0.07); +} diff --git a/design/forgeplan-design-system/tokens.json b/design/forgeplan-design-system/tokens.json new file mode 100644 index 00000000..7f7813a0 --- /dev/null +++ b/design/forgeplan-design-system/tokens.json @@ -0,0 +1,92 @@ +{ + "$schema": "https://design-tokens.github.io/community-group/format/", + "meta": { + "name": "ForgePlan", + "version": "1.1.0", + "canonicalAccent": "#FF6B35", + "modules": { + "base": "tokens.css", + "graph": "tokens.graph.css" + }, + "sources": { + "base": "website/src/styles audit, 2026-07-25", + "ported-v1.1": "forgeplan-web template/src/app/styles/app.css, neutrals rebased onto the canonical palette, 2026-08-14" + }, + "deprecated": { + "--accent": { + "value": "#FF5A1F", + "replacement": "--forge-ember", + "note": "For normal text on the light theme use --forge-ember-text, not --forge-ember." + } + } + }, + "color": { + "bg": {"dark": "#0D0D0D", "light": "#F5F5F0", "status": "fact"}, + "fg": {"dark": "#E8E8E8", "light": "#1A1A1A", "status": "fact"}, + "surface": {"dark": "#161616", "light": "#FFFFFF", "status": "fact"}, + "line": {"dark": "#3A3A3A", "light": "#D4D4D0", "status": "fact"}, + "dim": {"dark": "#949494", "light": "#6B6B6B", "status": "fact"}, + "ember": {"dark": "#FF6B35", "light": "#FF6B35", "status": "fact"}, + "emberText": {"dark": "#FF6B35", "light": "#C94400", "status": "proposal"}, + "emberSoft": {"dark": "#FF8A5B", "light": "#D94D1B", "status": "proposal"}, + "success": {"dark": "#28C840", "light": "#28C840", "status": "fact"}, + "successText": {"dark": "#28C840", "light": "#166534", "status": "proposal"}, + "error": {"dark": "#EF4444", "light": "#EF4444", "status": "fact"}, + "errorText": {"dark": "#EF4444", "light": "#991B1B", "status": "proposal"}, + "warning": {"dark": "#F59E0B", "light": "#F59E0B", "status": "proposal"}, + "warningText": {"dark": "#F59E0B", "light": "#92400E", "status": "proposal"}, + "info": {"dark": "#60A5FA", "light": "#60A5FA", "status": "proposal"}, + "infoText": {"dark": "#60A5FA", "light": "#1E3A8A", "status": "proposal"}, + "dim2": {"dark": "#6B6B6B", "light": "#98938A", "status": "ported-v1.1"}, + "dim3": {"dark": "#4A4A4A", "light": "#C4BFB5", "status": "ported-v1.1"}, + "surface2": {"dark": "#1C1C1C", "light": "#EFEFE8", "status": "ported-v1.1"}, + "scrim": {"dark": "rgba(0,0,0,0.60)", "light": "rgba(15,13,10,0.42)", "status": "ported-v1.1"}, + "overlay": {"dark": "rgba(13,13,13,0.85)", "light": "rgba(245,245,240,0.88)", "status": "ported-v1.1"}, + "onEmber": {"dark": "#1A1A1A", "light": "#1A1A1A", "status": "ported-v1.1", "note": "Primary button label is ALWAYS dark on ember; white fails contrast (2.84:1)."} + }, + "graph": { + "$module": "tokens.graph.css", + "$status": "ported-v1.1", + "$note": "Data-viz palette for graph/map/canvas surfaces; distinct from the one-accent brand rule. Ported from forgeplan-web, neutrals rebased on the canonical palette. The forgeplan-web 'orch' theme is app-specific and not part of the canon.", + "edge": ["default", "soft", "informs", "refines", "contains", "supersedes"], + "canvas": ["stroke", "stroke-2", "stroke-soft", "stroke-faint", "label", "label-faded", "label-strong", "stroke-on-fill", "overlay"], + "node": ["border", "fg"], + "map": ["zone", "zone-line", "clay", "olive", "accent-cyan", "accent-emerald", "accent-violet", "accent-amber", "accent-rose", "accent-orange", "accent-slate"], + "dotGrid": ["color", "size", "radius"] + }, + "font": { + "sans": {"value": "'Space Grotesk', ui-sans-serif, system-ui, -apple-system, sans-serif", "status": "fact"}, + "mono": {"value": "'Geist Mono', ui-monospace, SFMono-Regular, Menlo, monospace", "status": "fact"} + }, + "fontSize": { + "xs": {"value": "0.75rem", "status": "proposal"}, + "sm": {"value": "0.875rem", "status": "fact"}, + "base": {"value": "1rem", "status": "fact"}, + "lg": {"value": "1.125rem", "status": "fact"}, + "xl": {"value": "1.25rem", "status": "proposal"}, + "2xl": {"value": "1.5rem", "status": "fact"}, + "3xl": {"value": "2rem", "status": "fact"}, + "4xl": {"value": "2.5rem", "status": "fact"}, + "5xl": {"value": "3rem", "status": "proposal"}, + "6xl": {"value": "4rem", "status": "proposal"} + }, + "space": { + "0": "0", "1": "0.25rem", "2": "0.5rem", "3": "0.75rem", + "4": "1rem", "5": "1.25rem", "6": "1.5rem", "8": "2rem", + "10": "2.5rem", "12": "3rem", "16": "4rem", "20": "5rem", "24": "6rem", + "status": "proposal" + }, + "radius": { + "none": {"value": "0", "status": "fact"}, + "control": {"value": "2px", "status": "proposal"}, + "code": {"value": "3px", "status": "proposal-normalized"}, + "round": {"value": "50%", "status": "fact-exception"} + }, + "layout": { + "max": {"value": "1280px", "status": "fact"}, + "gutter": {"value": "32px", "status": "fact"}, + "headerExpanded": {"value": "88px", "status": "fact"}, + "headerCompact": {"value": "36px", "status": "fact"}, + "targetMin": {"value": "44px", "status": "proposal-requirement"} + } +} diff --git a/design/source-materials/forgeplan-cheat-sheets-source.ru.md b/design/source-materials/forgeplan-cheat-sheets-source.ru.md new file mode 100644 index 00000000..798fdaba --- /dev/null +++ b/design/source-materials/forgeplan-cheat-sheets-source.ru.md @@ -0,0 +1,411 @@ +# Промпт для генерации гайдов и шпаргалок по ForgePlan + +> Скопируй всё, что ниже разделителя, и отдай модели целиком. +> Ссылки на первоисточники внутри — модель может по ним сходить и уточнить. + +--- + +## ЗАДАЧА + +Ты — технический писатель, специализирующийся на справочных материалах для разработчиков: шпаргалках (cheat sheets), быстрых справочниках (quick reference cards) и учебных гайдах. + +Тебе нужно создать **комплект справочных материалов по инструменту ForgePlan**. Ниже — полное описание инструмента. Опирайся на него как на первоисточник; проверить и дополнить можно по ссылкам в конце. + +**Языки:** сделай две версии — русскую и английскую. Это не перевод слово-в-слово: в каждой версии идиоматичный язык, но идентичное содержание и структура. Технические идентификаторы (имена команд, типов, полей) в обеих версиях остаются английскими. + +--- + +## ЧТО НУЖНО СОЗДАТЬ + +### 1. Одностраничная шпаргалка (главный артефакт) + +Формат: A4, помещается на один разворот, печатается без потерь. Плотность как у классических cheat sheet — таблицы, а не абзацы. + +Должна содержать: +- полный цикл работы одной строкой-схемой; +- команды, сгруппированные по задаче, а не по алфавиту; +- 10 типов артефактов с префиксами и назначением; +- формулы оценки надёжности; +- жизненный цикл записи (переходы состояний); +- обязательные поля доказательства (без них система тихо ломается — см. ниже); +- 5–7 «если застрял → делай это» строк. + +### 2. Шпаргалка по командам + +Все команды, сгруппированные функционально, с одной строкой описания и типичным примером. Отдельным столбцом — соответствующий инструмент для агентов (MCP), где он есть. + +### 3. Шпаргалка «выбор глубины» + +Матрица «какая задача → какие записи нужны». Главная ошибка новичка — заводить все 10 типов на каждую задачу; шпаргалка должна это предотвращать. + +### 4. Гайд для начинающего + +Путь от нуля до первой завершённой задачи. Один сквозной пример, не абстракции. Формат: пронумерованные шаги с реальными командами и тем, что увидишь в ответ. + +### 5. Гайд «ежедневная работа» + +Для того, кто уже начал. Утренняя проверка, работа в течение дня, закрытие задачи, что делать при типовых проблемах. + +### 6. Визуальные схемы + +Диаграммы в Mermaid (чтобы рендерились на GitHub и в большинстве вики): +- полный цикл разработки; +- граф связей между типами записей; +- жизненный цикл состояний; +- дерево выбора глубины. + +--- + +# ЧТО ТАКОЕ FORGEPLAN + +## В одном абзаце + +ForgePlan — инструмент командной строки на Rust, который ведёт проект от идеи до реализации через структурированные записи: требования, архитектурные предложения, решения, спецификации, доказательства. Главная идея — **решение без доказательства не считается решением**. Каждая запись получает численную оценку надёжности, вычисленную по слабейшему звену её доказательной цепочки. Работает локально, без облака, один бинарный файл. Записи хранятся как обычные markdown-файлы в git. + +**Версия на момент написания:** 0.33.0. **76 команд CLI, 73 инструмента для агентов, 3000+ тестов.** + +## Проблема, которую решает + +В обычной разработке решения растворяются: почему выбрали эту библиотеку — знает один человек, и он ушёл. Почему тут такой лимит — «исторически сложилось». Через полгода никто не может сказать, актуально ли решение и на чём оно основывалось. + +Классический ответ — вести ADR (записи архитектурных решений). ForgePlan идёт дальше в трёх местах: + +1. **Решение обязано иметь доказательство.** Не «мы посовещались и решили», а измерение, тест, бенчмарк — с указанием, где его взяли. +2. **Надёжность считается, а не декларируется.** Есть формула, и она даёт число. +3. **Решения протухают.** У записи есть срок годности. Истёк — надёжность падает до 0.1, запись всплывает в проверке здоровья. + +## Философия: файлы главные + +Все записи — обычные markdown-файлы в папке `.forgeplan/` внутри репозитория. Они лежат в git, читаются глазами, правятся в любом редакторе, сливаются как обычный код. + +Векторная база (для семантического поиска) — **производная**. Её можно удалить и пересобрать одной командой. Это записано как архитектурное решение ADR-003 и защищено тестом-сторожем. + +Практическое следствие: **правь записи только через команды инструмента**, а не текстовым редактором напрямую. Прямая правка рассинхронизирует индекс, и поиск начнёт врать. Восстановление есть, но лучше не доводить. + +--- + +# АРТЕФАКТЫ: 10 ТИПОВ + +| Тип | Префикс | Отвечает на вопрос | Когда нужен | +|---|---|---|---| +| **PRD** | `prd-` | Что делаем и зачем | Фича с выбором. Не нужен для багфикса | +| **RFC** | `rfc-` | Как построим | Архитектура неочевидна, работы больше дня | +| **ADR** | `adr-` | Почему именно так | Решение необратимо или дорого менять | +| **Spec** | `spec-` | Как именно работает | Меняется контракт API или модель данных | +| **Epic** | `epic-` | Группировка | Задача не влезает в один PRD | +| **Evidence** | `evid-` | Доказательство | Всегда, когда есть что измерить | +| **Problem** | `prob-` | Найденный дефект | Проблема должна пережить сессию | +| **Solution** | `sol-` | 2–3 варианта решения | Выбор между подходами | +| **Note** | `note-` | Микро-решение | Мелочь, которую жаль потерять. Живёт 90 дней | +| **Refresh** | `ref-` | Пересмотр | Решение протухло, надо переоценить | + +**Иерархия:** Epic → PRD[] → Spec[] + RFC[] + ADR[]. Потомок ссылается на родителя. + +**Главное правило:** записи не удаляют, а **замещают**. История решений — ценность. + +**Активно используются шесть:** PRD, RFC, ADR, Spec, Evidence, Problem. Остальные — по необходимости. + +--- + +# ВЫБОР ГЛУБИНЫ + +Определяется одним вопросом: **насколько это необратимо?** + +| Сложность | Глубина | Что заводим | Разбор гипотез | +|---|---|---|---| +| Мелочь, откатывается за день | Tactical | ничего или Note | — | +| Фича 1–3 дня, есть выбор | Standard | PRD → RFC | желателен | +| Необратимо, 1–2 недели | Deep | PRD → Spec → RFC → ADR | **обязателен** | +| Затрагивает команды, стратегия | Critical | Epic → PRD[] → Spec[] → RFC[] → ADR[] | **обязателен + ревью** | + +Определить помогает `forgeplan route "описание задачи"`. + +**Антипаттерн, от которого шпаргалка должна защищать:** заводить все типы на каждую задачу. Конвейер — ориентир, а не бюрократия. + +--- + +# ПОЛНЫЙ ЦИКЛ + +``` +1. Маршрут: forgeplan route "задача" → определить глубину +2. Форма: forgeplan new prd "Название" → сразу заполнить обязательные разделы +3. Проверка: forgeplan validate PRD-XXX → 0 ошибок обязательных разделов +4. Гипотезы: forgeplan reason PRD-XXX → 3+ гипотезы (Deep/Critical: обязательно) +5. Ветка: git checkout -b feat/xxx +6. Код: реализация + тест на каждую публичную функцию +7. Тесты: cargo test → 0 падений +8. Формат: cargo fmt --check → 0 расхождений +9. Линт: cargo clippy -- -D warnings → 0 предупреждений +10. Аудит: минимум 2 независимых ревьюера → закрыть все критичные находки +11. Доказательство: forgeplan new evidence + link → оценка > 0 +12. Активация: forgeplan activate PRD-XXX +13. PR: git push && gh pr create +``` + +**Для мелочи (Tactical):** маршрут → ветка → код → тест → формат → линт → коммит. Без записей и PR. + +**Работа не считается сделанной,** пока: PRD заполнен + проверка пройдена + гипотезы разобраны + доказательство есть + оценка > 0 + запись активирована. + +--- + +# ОЦЕНКА НАДЁЖНОСТИ + +## Слабейшее звено + +``` +R_eff = min(оценки всех доказательств) +``` + +**Не среднее.** Одно слабое доказательство тянет вниз всю цепочку — это намеренно. Цепь рвётся по слабейшему звену, а не по среднему. + +## Три оси доказательства (F-G-R) + +| Ось | Что мерит | +|---|---| +| **Formality** | Соответствие схеме: сколько обязательных полей заполнено | +| **Granularity** | Плотность деталей: насколько подробно | +| **Reliability** | Достоверность источника | + +## Штраф за несовпадение контекста + +Доказательство, полученное в одних условиях и применённое в других, стоит меньше: + +| Уровень | Что значит | Штраф | +|---|---|---| +| CL3 | Тот же контекст | 0.0 | +| CL2 | Соседний контекст, тот же домен | 0.1 | +| CL1 | Другой контекст | 0.4 | +| CL0 | Противоречащий контекст | 0.9 | + +## Протухание + +У записи есть срок годности `valid_until`. Истёк — надёжность падает до **0.1**, запись всплывает в `forgeplan stale`. + +## Производный статус + +`UNDERFRAMED → FRAMED → EXPLORING → COMPARED → DECIDED → APPLIED` — вычисляется, не ставится руками. + +--- + +# ⚠️ КРИТИЧНО: обязательные поля доказательства + +Тело записи-доказательства **обязано** содержать блок: + +```markdown +## Structured Fields + +verdict: supports # supports / weakens / refutes +congruence_level: 3 # 3 = тот же контекст … 0 = противоречащий +evidence_type: measurement # measurement / test / benchmark / audit +``` + +**Без этих трёх полей парсер тихо ставит CL0 (штраф 0.9), и надёжность обнуляется.** Ошибки не будет — просто оценка окажется нулевой, и непонятно почему. + +Это самая частая ошибка новичка. **Вынеси её в шпаргалку заметно** — рамкой, цветом, отдельным блоком. + +--- + +# ЖИЗНЕННЫЙ ЦИКЛ + +``` +draft ──activate──> active ──┬──supersede──> superseded (конечное) + ├──deprecate──> deprecated (конечное) + └──(срок истёк)──> stale + │ + renew ─────────────────┤ → active + reopen ────────────────┘ → deprecated + новый draft +``` + +| Команда | Что делает | +|---|---| +| `forgeplan review ` | Проверить готовность | +| `forgeplan activate ` | draft → active (с проверкой) | +| `forgeplan supersede --by <новый>` | Заменено новым решением | +| `forgeplan deprecate --reason "..."` | Отменено | +| `forgeplan renew --reason --until` | Продлить протухшее | +| `forgeplan reopen --reason` | Пересмотреть заново | + +**Активировать без кода и доказательства нельзя** — надёжность должна быть больше нуля. + +--- + +# КОМАНДЫ ПО ЗАДАЧАМ + +## Каждый день + +| Команда | Зачем | +|---|---| +| `forgeplan health` | Панель здоровья: пробелы, риски, слепые зоны, что делать | +| `forgeplan list` | Все записи | +| `forgeplan get ` | Прочитать запись | +| `forgeplan search "запрос"` | Поиск по смыслу, не по словам | +| `forgeplan graph` | Граф связей (Mermaid) | + +## Создать и заполнить + +| Команда | Зачем | +|---|---| +| `forgeplan new <тип> "Название"` | Создать из шаблона | +| `forgeplan update --body @файл` | Заменить тело | +| `forgeplan link <из> <в> --relation <тип>` | Связать | +| `forgeplan unlink <из> <в>` | Разорвать связь | +| `forgeplan validate ` | Проверить обязательные разделы | +| `forgeplan generate ` | Заполнить через модель | + +## Оценить и обдумать + +| Команда | Зачем | +|---|---| +| `forgeplan score ` | Надёжность | +| `forgeplan reason ` | Разбор гипотез | +| `forgeplan route "задача"` | Определить глубину | +| `forgeplan decompose ` | Разбить на подзадачи | +| `forgeplan estimate ` | Оценка трудоёмкости | +| `forgeplan fgr ` | Разложить по трём осям | + +## Диагностика + +| Команда | Что показывает | +|---|---| +| `forgeplan health` | Общая панель | +| `forgeplan blindspots` | Решения без доказательств, записи-сироты | +| `forgeplan blocked` | Что заблокировано и чем | +| `forgeplan stale` | Протухшие | +| `forgeplan anomalies` | Аномалии с уровнем важности и предложением как чинить | +| `forgeplan drift` | Решения, чей код изменился после принятия | +| `forgeplan coverage` | Покрытие модулей решениями | +| `forgeplan gaps` | Нарушения конвейера по глубине | +| `forgeplan order` | Порядок работ (топологический) | +| `forgeplan tree` | Дерево записей | + +Поиск противоречий (`forgeplan_contradictions`) существует только среди инструментов для агентов, отдельной команды CLI для него нет. + +## Несколько агентов одновременно + +| Команда | Зачем | +|---|---| +| `forgeplan dispatch --agents N` | План распределения без конфликтов | +| `forgeplan claim --ttl 30` | «Я беру эту запись» | +| `forgeplan release ` | «Закончил» | +| `forgeplan claims` | Кто что взял | + +## Служебное + +| Команда | Зачем | +|---|---| +| `forgeplan init -y` | Развернуть в проекте | +| `forgeplan export --output файл.json` | Выгрузить всё | +| `forgeplan import файл.json` | Загрузить обратно | +| `forgeplan scan-import` | Пересобрать индекс из markdown | +| `forgeplan serve` | Запустить сервер для агентов | +| `forgeplan watch` | Следить за папкой и синхронизировать | +| `forgeplan playbook run <имя>` | Выполнить сценарий | +| `forgeplan journal` | Хронология решений | +| `forgeplan undo-last` | Отменить последнюю операцию | +| `forgeplan restore ` | Восстановить удалённое (30 дней) | + +**Полный список (76):** `activity activity-stats restore undo-last init new list status tag untag discover validate score estimate link unlink graph search stale session progress claim claims decay calibrate-estimate calibrate promote generate reason decompose context get update delete route review activate supersede deprecate release release-notes renew reopen setup-skill fpf gaps fgr scan coverage dispatch drift blocked blindspots anomalies journal health capture export import scan-import tree order phase phase-advance migrate ci-assign-id migrate-dry-run migrate-secrets reconcile-ids reindex embed log remember recall watch git-sync serve mcp playbook ingest plugins` + +Псевдоним команды: `fpl`. + +--- + +# ТИПЫ СВЯЗЕЙ + +Связи типизированы. Допустимы ровно эти: + +`informs` · `based_on` · `supersedes` · `contradicts` · `refines` · `supports` · `demonstrates` · `covers` · `triangulates` · `references` · `belongs_to` + +Чаще всего: доказательство `informs` запись; потомок `based_on` родителя; новое решение `supersedes` старое. + +--- + +# РАБОТА С АГЕНТАМИ + +ForgePlan умеет работать как сервер инструментов для ИИ-агентов — **73 инструмента**, зеркалящих команды. + +Каждый ответ содержит подсказку следующего шага, чтобы агент не гадал: + +| Маркер | Смысл | +|---|---| +| `Next: <команда>` | Основное действие — выполнить как есть | +| `Or: <команда>` | Альтернатива | +| `Wait: <условие>` | Ждать и повторить | +| `Done.` | Готово | +| `Fix: <команда>` | Исправление ошибки | + +В JSON: поле `_next_action`. + +--- + +# ЭКОСИСТЕМА: 20 ПЛАГИНОВ + +Отдельный каталог расширений для Claude Code: + +| Плагин | Что даёт | +|---|---| +| `fpl-skills` | Флагман: 40 инженерных навыков, включая диспетчер `/smith` | +| `forgeplan-workflow` | Команды `/forge-cycle`, `/forge-audit` | +| `fpf` | Каркас мышления от первых принципов | +| `fpl-hsmem` | Долговременная память между сессиями | +| `agents-core` / `agents-pro` / `agents-domain` | Наборы специализированных агентов | +| `agents-tdd` / `agents-bmad` / `agents-sparc` / `agents-canvas` | Методологии: TDD, greenfield, пофазная разработка, дизайн-система → код | +| `forgeplan-brownfield-pack` | 12 навыков для разбора чужого кода | +| `forgeplan-map-pack` | Конвейер из 8 агентов: строит интерактивную карту проекта | +| `laws-of-ux` | 30 законов UX + ревьюер фронтенда | +| `fp-cookbook` | Сборник практических рецептов | + +Ключевой: **`/smith`** — читает состояние проекта, относит ситуацию к одному из 14 типовых положений и выдаёт план: кого запускать и в каком порядке. Сам ничего не делает. + +--- + +# ЧАСТЫЕ ОШИБКИ + +Обязательно в шпаргалку: + +1. **Доказательство без блока `## Structured Fields`** → надёжность 0, без предупреждения. Самая частая. +2. **Правка `.forgeplan/*.md` текстовым редактором** → индекс рассинхронизируется, поиск врёт. Только через команды. +3. **Заведение всех 10 типов на каждую задачу** → бюрократия вместо пользы. Глубина определяется необратимостью. +4. **Активация без кода и доказательства** → надёжность 0, запись выглядит готовой, но пустая. +5. **Заготовка PRD, оставленная незаполненной** → мусор в графе. +6. **Игнорирование `forgeplan health`** → долг копится, слепые зоны растут. + +--- + +# ИСТОЧНИКИ + +- **Сайт:** https://forgeplan.dev — документация, гайды, блог; русская и английская версии +- **Репозиторий:** https://github.com/ForgePlan/forgeplan +- **Каталог плагинов:** https://github.com/ForgePlan/marketplace +- **Установка:** `brew install forgeplan/tap/forgeplan` + На Homebrew 6.0+ сначала: `brew trust forgeplan/tap` + +Внутри репозитория: +- `docs/methodology/FORGEPLAN-GUIDE.md` — полное руководство +- `docs/methodology/GLOSSARY.md` — словарь терминов +- `docs/methodology/HOW-TO-USE.md` — практическое применение +- `docs/methodology/DEPTH-CALIBRATION.md` — выбор глубины +- `docs/methodology/EVIDENCE-PROTOCOL.md` — протокол доказательств +- `docs/methodology/USAGE-BY-ROLE.md` — по ролям +- `CLAUDE.md` — инструкции для ИИ-агентов, включая жёсткие запреты + +--- + +# ТРЕБОВАНИЯ К РЕЗУЛЬТАТУ + +**Плотность.** Шпаргалка — это таблицы и списки, а не проза. Читают взглядом, а не построчно. + +**Приоритет.** Самое частое — вверху и заметно. Блок `## Structured Fields` — выделить рамкой. + +**Примеры настоящие.** Не ``, а `forgeplan new prd "Streaming ответов модели"`. + +**Печать.** Главная шпаргалка обязана нормально печататься на A4 чёрно-белым. + +**Форматы:** markdown (основной), HTML с печатным CSS (для веба и печати), Mermaid для схем. + +**Тон:** прямой, без маркетинга. Это справочник, не реклама. Пиши так, будто читатель уже решил пользоваться и хочет быстро вспомнить команду. + +**Чего не делать:** +- не выдумывать команды, которых нет в списке выше; +- не преувеличивать возможности — инструмент локальный, без облака и совместной работы в реальном времени; +- не смешивать два языка в одном документе. diff --git a/design/visual-guides/00-design-system-foundation.png b/design/visual-guides/00-design-system-foundation.png new file mode 100644 index 00000000..24b49c75 Binary files /dev/null and b/design/visual-guides/00-design-system-foundation.png differ diff --git a/design/visual-guides/01-quick-start-portrait.png b/design/visual-guides/01-quick-start-portrait.png new file mode 100644 index 00000000..bbff7637 Binary files /dev/null and b/design/visual-guides/01-quick-start-portrait.png differ diff --git a/design/visual-guides/02-development-cycle-16x9.png b/design/visual-guides/02-development-cycle-16x9.png new file mode 100644 index 00000000..957b3b34 Binary files /dev/null and b/design/visual-guides/02-development-cycle-16x9.png differ diff --git a/design/visual-guides/03-depth-selection-16x9.png b/design/visual-guides/03-depth-selection-16x9.png new file mode 100644 index 00000000..8c86677b Binary files /dev/null and b/design/visual-guides/03-depth-selection-16x9.png differ diff --git a/design/visual-guides/04-artifact-types-16x9.png b/design/visual-guides/04-artifact-types-16x9.png new file mode 100644 index 00000000..e2efd34d Binary files /dev/null and b/design/visual-guides/04-artifact-types-16x9.png differ diff --git a/design/visual-guides/05-create-and-work-16x9.png b/design/visual-guides/05-create-and-work-16x9.png new file mode 100644 index 00000000..182bd529 Binary files /dev/null and b/design/visual-guides/05-create-and-work-16x9.png differ diff --git a/design/visual-guides/06-diagnostics-and-agents-16x9.png b/design/visual-guides/06-diagnostics-and-agents-16x9.png new file mode 100644 index 00000000..8d69eb46 Binary files /dev/null and b/design/visual-guides/06-diagnostics-and-agents-16x9.png differ diff --git a/design/visual-guides/07-evidence-protocol-16x9.png b/design/visual-guides/07-evidence-protocol-16x9.png new file mode 100644 index 00000000..e5814b54 Binary files /dev/null and b/design/visual-guides/07-evidence-protocol-16x9.png differ diff --git a/design/visual-guides/08-reliability-fgr-16x9.png b/design/visual-guides/08-reliability-fgr-16x9.png new file mode 100644 index 00000000..f67ce493 Binary files /dev/null and b/design/visual-guides/08-reliability-fgr-16x9.png differ diff --git a/design/visual-guides/09-lifecycle-16x9.png b/design/visual-guides/09-lifecycle-16x9.png new file mode 100644 index 00000000..9bffda11 Binary files /dev/null and b/design/visual-guides/09-lifecycle-16x9.png differ diff --git a/design/visual-guides/10-daily-work-16x9.png b/design/visual-guides/10-daily-work-16x9.png new file mode 100644 index 00000000..ca0f036a Binary files /dev/null and b/design/visual-guides/10-daily-work-16x9.png differ