generated from coulomb/repo-seed
Plan WP-0017: whynot-design adoption (tokens + CSS only)
Add cross-framework analysis to history/ and WP-0017 workplan for the tokens+CSS phase of adopting ~/whynot-design. Component port deferred until upstream ships Lit web components and missing atoms (Card, Modal, Input, Table, Toast). Decisions captured: vendor (not npm), big-bang swap (not pilot), keep off-spec red for btn-danger until upstream defines one.
This commit is contained in:
361
history/2026-05-23-whynot-design-cross-framework-analysis.md
Normal file
361
history/2026-05-23-whynot-design-cross-framework-analysis.md
Normal file
@@ -0,0 +1,361 @@
|
|||||||
|
---
|
||||||
|
date: 2026-05-23
|
||||||
|
topic: whynot-design adoption — cross-framework analysis
|
||||||
|
status: research / decision pending
|
||||||
|
author: claude (opus-4.7)
|
||||||
|
related:
|
||||||
|
- ~/whynot-design (the React DS in question)
|
||||||
|
- ~/whynot-control (the org control surface — explicitly out of scope)
|
||||||
|
- vergabe-teilnahme (the consuming Django app)
|
||||||
|
follow-ups:
|
||||||
|
- workplan: VERGABE_TEILNAHME-WP-0017 (whynot-design adoption) — not yet drafted, depends on strategy decision below
|
||||||
|
- possible new repo: whynot-design-django — see §5
|
||||||
|
---
|
||||||
|
|
||||||
|
# whynot-design — cross-framework adoption analysis
|
||||||
|
|
||||||
|
> Persisted from a research conversation on 2026-05-23. The conversation was triggered
|
||||||
|
> by the question "should vergabe-teilnahme adopt the whynot design system, and how?"
|
||||||
|
> The strategic question opened up because whynot-design ships React components
|
||||||
|
> while vergabe-teilnahme is Django + HTMX + Tailwind.
|
||||||
|
|
||||||
|
## 1. The headline insight
|
||||||
|
|
||||||
|
There is **no community** around "React → Django component porting." That pattern
|
||||||
|
doesn't exist as a tool, library, or codified practice. The reason: cross-framework
|
||||||
|
UI sharing has, since ~2020, converged on **Web Components** as the standard answer.
|
||||||
|
|
||||||
|
Every major design system that supports multiple frameworks (Shoelace / Web Awesome,
|
||||||
|
IBM Carbon, Adobe Spectrum, Salesforce Lightning, Material Web) either ships Web
|
||||||
|
Components or maintains parallel hand-rolled implementations per framework. There is
|
||||||
|
no third option that the industry has validated.
|
||||||
|
|
||||||
|
The W3C Design Tokens Community Group spec reached its **first stable version in
|
||||||
|
October 2025**, with Style Dictionary, Figma, Penpot, Tokens Studio, and others as
|
||||||
|
reference implementations. Tokens as a cross-framework contract are now genuinely
|
||||||
|
portable; *components* still aren't, except via web components.
|
||||||
|
|
||||||
|
The strategic question therefore reshapes itself: **do we accept the
|
||||||
|
parallel-implementations cost, or do we change what `whynot-design` actually ships?**
|
||||||
|
|
||||||
|
## 2. Research findings — existing approaches and their communities
|
||||||
|
|
||||||
|
| Approach | What it is | Community / activity | Fit for whynot |
|
||||||
|
|---|---|---|---|
|
||||||
|
| **Web Components** (Lit, Stencil) | Browser-standard custom elements; works in any framework | Very active; React 19 finally scores perfect on custom-elements-everywhere.com | **High** — best general answer if we're willing to refactor whynot-design |
|
||||||
|
| **Shoelace / Web Awesome** | Pre-built Web Components UI kit (Shoelace's successor) | Large, active OSS community | Not direct (competing DS), but proves the model. Has explicit HTMX integration guides |
|
||||||
|
| **Stencil JS** | Compiler that emits framework-specific bindings from one source | Mature; IBM/Apple use it; declining mindshare vs. Lit | **Medium** — heavier than Lit but generates per-framework wrappers automatically |
|
||||||
|
| **Style Dictionary + DTCG tokens** | One token file → CSS / Tailwind / iOS / Android / Flutter | W3C-backed, stable spec since 2025-10 | **High** — should be our token pipeline regardless of component choice |
|
||||||
|
| **Carbon / Spectrum / Lightning / Material pattern** | Single design source, hand-maintained parallel packages per framework | Active but they're 100+ engineer teams | **Low** at our scale — the "expensive but principled" reference path |
|
||||||
|
| **Single-spa / micro-frontends** | Multiple frameworks coexisting in one app | Niche, mostly enterprise integration | **Off-topic** — not about sharing components, about hosting heterogeneous apps |
|
||||||
|
| **django-cotton / django-components / django-bird** | Django-template-native component libraries; HTMX-friendly | Active, growing in 2024–2026; mature enough to depend on | **High** as the *Django-side runtime* — but doesn't solve cross-framework, just gives Django a real component model |
|
||||||
|
| **"Port React to Django" libraries** | (doesn't exist) | None | None |
|
||||||
|
|
||||||
|
**Read of the field:** the world has settled on "tokens are cross-framework;
|
||||||
|
components are framework-native." Most teams either pick web components (one
|
||||||
|
implementation, runs anywhere with some friction) or accept parallel implementations
|
||||||
|
from a shared design language.
|
||||||
|
|
||||||
|
## 3. Three viable strategies for whynot's situation
|
||||||
|
|
||||||
|
**Strategy A — Pivot whynot-design to Web Components.**
|
||||||
|
Rewrite `Atoms.jsx` + `Chrome.jsx` as Lit components. Ship one runtime artefact
|
||||||
|
(`@whynot/design`) that Django + HTMX templates can drop into a page via plain
|
||||||
|
`<whynot-button>` tags. No React dependency anywhere. Tailwind / CSS variables
|
||||||
|
continue to drive theming.
|
||||||
|
|
||||||
|
**Strategy B — Keep whynot-design React-canonical; add a parallel `whynot-design-django` repo.**
|
||||||
|
Treat the React JSX as the *visual + API specification*. Hand-port to Django
|
||||||
|
partials in a separate, reusable repo so vergabe-teilnahme and future Django
|
||||||
|
consumers share one implementation. Tokens stay in whynot-design (single source).
|
||||||
|
|
||||||
|
**Strategy C — Tokens only; components are framework-local forever.**
|
||||||
|
Don't promise component parity. Vergabe re-implements whynot's *look* using the
|
||||||
|
tokens but its components live and die in vergabe-teilnahme. Other Django apps
|
||||||
|
would do the same fork. Bernd implied this is unsatisfying — he wants a real
|
||||||
|
component library for cross-project consistency.
|
||||||
|
|
||||||
|
The real choice is **A vs. B**.
|
||||||
|
|
||||||
|
## 4. Pros / cons — A (Web Components) vs. B (parallel Django repo)
|
||||||
|
|
||||||
|
### Strategy A — Pivot to Web Components (Lit)
|
||||||
|
|
||||||
|
**Pros**
|
||||||
|
- *One* implementation. Zero divergence risk. Bug fixes ship once.
|
||||||
|
- Standards-backed; outlives any framework choice. Works in vanilla HTML, Django
|
||||||
|
templates, future Vue/Svelte/Solid apps, marketing sites, claude.ai artifacts.
|
||||||
|
- HTMX swaps work cleanly — web components are just DOM; HTMX doesn't care.
|
||||||
|
- The community is *here*. Tutorials, debugging tools, Storybook integration,
|
||||||
|
accessibility testing infrastructure all exist.
|
||||||
|
- The Claude atelier in claude.ai can still output JSX prototypes; Lit ports are
|
||||||
|
mechanical once the design is decided.
|
||||||
|
|
||||||
|
**Cons**
|
||||||
|
- One-time rewrite cost of the existing 11 React components. Real, but small
|
||||||
|
(~267 lines of JSX, not a library of 200 components).
|
||||||
|
- Web components have Shadow DOM trade-offs: form-association, deep style scoping,
|
||||||
|
and slotting have learning curves. Workable but real friction.
|
||||||
|
- React-shaped APIs (`<Button variant="primary">`) translate to attributes /
|
||||||
|
properties (`<wn-button variant="primary">`). Slightly less ergonomic in React,
|
||||||
|
equally ergonomic everywhere else.
|
||||||
|
- Lose the claude.ai → npm symmetry: claude.ai design tool outputs JSX; you'd
|
||||||
|
convert each new component.
|
||||||
|
- Whoever maintains whynot-design has to learn Lit (small surface area, but new
|
||||||
|
vocabulary).
|
||||||
|
|
||||||
|
### Strategy B — Parallel `whynot-design-django` repo
|
||||||
|
|
||||||
|
**Pros**
|
||||||
|
- Each implementation is idiomatic for its stack. Django templates feel like
|
||||||
|
Django; React feels like React.
|
||||||
|
- No new technology to learn. Both repos use mature, well-understood patterns.
|
||||||
|
- Django consumers get to use `django-cotton` or `django-bird` — real ergonomics,
|
||||||
|
not a half-port.
|
||||||
|
- claude.ai → JSX → Lit conversion step is avoided. The atelier output is
|
||||||
|
*directly* the React reference.
|
||||||
|
|
||||||
|
**Cons**
|
||||||
|
- *Two* implementations forever. Every component change needs both sides updated;
|
||||||
|
PRs need cross-repo review discipline.
|
||||||
|
- API drift is inevitable. By v0.5 the React `<Button>` and Django `{% button %}`
|
||||||
|
will have diverged in props/slots/behavior unless enforced with conformance tests.
|
||||||
|
- A *third* consumer stack (Vue, vanilla HTML, native mobile) means a *third* repo.
|
||||||
|
Cost scales linearly with the number of stacks; A's cost is roughly constant.
|
||||||
|
- The "community" of "people maintaining a React→Django twin DS" is exactly Bernd
|
||||||
|
and whoever he recruits. No prior art to lean on.
|
||||||
|
- Visual regression testing has to run twice (Playwright against examples in both
|
||||||
|
repos) to ensure parity.
|
||||||
|
|
||||||
|
### Recommendation
|
||||||
|
|
||||||
|
**Strategy A is the right long-term answer**; B is the right *interim* answer if
|
||||||
|
we don't want to halt vergabe-teilnahme to do a Lit rewrite first.
|
||||||
|
|
||||||
|
A real third path: **A scheduled, B today.** Build B as a reusable Django port now
|
||||||
|
to unblock vergabe-teilnahme; treat it as the *bridge* until whynot-design pivots
|
||||||
|
to Lit at, say, v0.5. The Django repo becomes obsolete when A lands — that's a
|
||||||
|
feature, not a bug; it forces a clear retirement decision instead of accumulating
|
||||||
|
tech debt.
|
||||||
|
|
||||||
|
If we don't want to commit to a future Lit pivot, then B is the right choice on its
|
||||||
|
own — just accept the linear-cost-per-stack reality.
|
||||||
|
|
||||||
|
## 5. Naming, establishing, workflow — if we go with B
|
||||||
|
|
||||||
|
### Naming proposals
|
||||||
|
|
||||||
|
| Candidate | Pros | Cons |
|
||||||
|
|---|---|---|
|
||||||
|
| **`whynot-design-django`** (recommended) | Mirrors `@whynot/design`. Unambiguous about stack. Discoverable. | Slightly long. |
|
||||||
|
| `whynot-django` | Short. | Ambiguous — sounds like a Django app, not a DS port. |
|
||||||
|
| `whynot-design-py` | Hedges for Jinja2/Flask later. | Vague — Python doesn't pick a template engine. |
|
||||||
|
| `whynot-dj` | Compact. | Cryptic. |
|
||||||
|
| `whynot-templates` | Honest about what it is. | Doesn't carry the "design" meaning. |
|
||||||
|
|
||||||
|
**Recommend `whynot-design-django`.** If a Jinja port appears, it gets its own repo
|
||||||
|
(`whynot-design-jinja`), not a confusing rename.
|
||||||
|
|
||||||
|
### Establishing the repo (concrete steps)
|
||||||
|
|
||||||
|
1. **Gitea org placement:** `gitea-remote:whynot/whynot-design-django.git` — same
|
||||||
|
org as `whynot-design`, signaling sibling status.
|
||||||
|
2. **Package shape:** a pip-installable Django app (`pyproject.toml`, importable as
|
||||||
|
`whynot_design`). Two install paths:
|
||||||
|
- `pip install git+ssh://...@v0.1.0` (matches whynot-design's tag-pinned discipline).
|
||||||
|
- For dev: editable install (`pip install -e ../whynot-design-django`).
|
||||||
|
3. **Layout** (matches Django conventions; mirrors whynot-design's structure):
|
||||||
|
```
|
||||||
|
whynot-design-django/
|
||||||
|
├── README.md ← restates the "match the React spec" contract
|
||||||
|
├── CONTRIBUTING.md ← parity rules: any change here must follow a whynot-design change
|
||||||
|
├── CHANGELOG.md
|
||||||
|
├── pyproject.toml
|
||||||
|
├── whynot_design/
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ ├── apps.py
|
||||||
|
│ ├── templates/whynot_design/
|
||||||
|
│ │ ├── atoms/eyebrow.html, tag.html, button.html, stage_dot.html, stamp.html, icon.html
|
||||||
|
│ │ ├── chrome/top_nav.html, sidebar.html, page_header.html, pipeline_strip.html
|
||||||
|
│ │ └── _base.html ← imports the CSS once
|
||||||
|
│ ├── templatetags/
|
||||||
|
│ │ └── whynot.py ← {% wn_button variant="primary" %}…{% endwn_button %}, etc.
|
||||||
|
│ └── static/whynot_design/
|
||||||
|
│ └── colors_and_type.css ← vendored from @whynot/design (synced)
|
||||||
|
├── tests/
|
||||||
|
│ ├── test_components.py ← Django test client, asserts rendered markup matches expected shape
|
||||||
|
│ └── parity/ ← Playwright comparison of Django render vs. React render
|
||||||
|
└── examples/ ← a Django demo project rendering every component
|
||||||
|
```
|
||||||
|
4. **Token sync:** a `scripts/sync-from-whynot-design.py` that copies
|
||||||
|
`colors_and_type.css` and `tokens/*.json` from a pinned whynot-design ref into
|
||||||
|
the static dir + generates a Django settings constant for tokens. Run on every
|
||||||
|
whynot-design version bump.
|
||||||
|
5. **Underlying component mechanism:** plain `{% include %}` partials (simplest, no
|
||||||
|
new dep), `django-cotton` (HTML-like syntax, very ergonomic, active community),
|
||||||
|
or `django-components` (most powerful, heaviest). My lean: **`django-cotton`** —
|
||||||
|
its `<c-button variant="primary">…</c-button>` syntax parallels React JSX best,
|
||||||
|
so the parity contract is more obvious.
|
||||||
|
|
||||||
|
### What changes in the workflow
|
||||||
|
|
||||||
|
Before:
|
||||||
|
```
|
||||||
|
claude.ai atelier ──► whynot-design ──► consumer
|
||||||
|
```
|
||||||
|
After:
|
||||||
|
```
|
||||||
|
claude.ai atelier ──► whynot-design ──┬─► whynot-design-django ──► vergabe-teilnahme (+ future Django apps)
|
||||||
|
│
|
||||||
|
├─► future stacks: whynot-design-jinja / -svelte / -vue / …
|
||||||
|
│
|
||||||
|
└─► tokens flow into all child repos via a sync script
|
||||||
|
```
|
||||||
|
|
||||||
|
Concretely, this adds three new ongoing obligations:
|
||||||
|
|
||||||
|
1. **Token sync gate.** When whynot-design ships a token change, the Django repo's
|
||||||
|
sync script must run before its next release. CI check: the static CSS in
|
||||||
|
`whynot-design-django` must hash-match the CSS at the pinned upstream tag.
|
||||||
|
2. **Component parity gate.** When whynot-design adds or modifies a component, an
|
||||||
|
issue is opened automatically in `whynot-design-django` referencing the upstream
|
||||||
|
PR. A release is blocked until the issue closes. Encode in `CONTRIBUTING.md`
|
||||||
|
first; later, a CI cross-repo check.
|
||||||
|
3. **Conformance tests.** Each component's Django partial has a Playwright snapshot
|
||||||
|
that's compared against the same component rendered in whynot-design's
|
||||||
|
`examples/whynot-control/`. Drift = failing build.
|
||||||
|
|
||||||
|
Vergabe-teilnahme's workplan therefore depends on **whynot-design-django** existing
|
||||||
|
first. The vergabe workplan becomes: install the new package, replace partials with
|
||||||
|
cotton/include tags, retheme.
|
||||||
|
|
||||||
|
## 6. Component-level inventory — whynot-design vs. vergabe-teilnahme
|
||||||
|
|
||||||
|
| whynot-design (React) | vergabe-teilnahme (Django) | Match | Gap action |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `Eyebrow` (mono uppercase label, fg-3) | — | Missing | New partial `atoms/eyebrow.html` |
|
||||||
|
| `Tag` (mono uppercase pill: default / active / draft) | `status_badge.html` (different semantics — domain statuses) | Partial | Replace `status_badge` content with `Tag` variants; keep status→variant mapping |
|
||||||
|
| `Button` (3 variants: primary / secondary / ghost; lucide icon support) | CSS classes `.btn-primary`, `.btn-secondary`, `.btn-danger`, `.btn-ghost` | Strong overlap; `btn-danger` not upstream | Adopt 3 base variants; propose `danger` upstream OR retire it (whynot's voice avoids red/destructive emphasis) |
|
||||||
|
| `StageDot` (S0–S4 signal levels with grey-ramp + yellow S4) | `phase_nav.html` (numbered phase circles: todo/active/done/warn) | Semantically different — *whynot stages* ≠ *vergabe phases* | Keep both as distinct atoms. Propose `PhaseDot` upstream OR keep vergabe-local |
|
||||||
|
| `Stamp` (yellow rotated "DRAFT") | — | Missing | New partial; useful for unfreigegeben items |
|
||||||
|
| `Icon` (lucide via `data-lucide`) | inline SVGs / class-based | Missing as a component | New partial that wraps lucide; pull lucide JS into base.html |
|
||||||
|
| `TopNav` | `topbar.html` | Both exist; styling and density differ significantly | Reskin vergabe's topbar to whynot's structure (search box + primary action right-aligned) |
|
||||||
|
| `Sidebar` | `sidebar.html` | Both exist; nav model differs (vergabe has phase grouping; whynot has Work / Control docs grouping) | Adopt whynot's chrome (item style, eyebrow section headers) but keep vergabe's nav items |
|
||||||
|
| `PageHeader` (eyebrow + h1 + lede + actions) | — (inline per template) | Missing | New partial; refactor all page templates to use it |
|
||||||
|
| `PipelineStrip` (5-stage horizontal indicator) | `phase_nav.html` (vertical / different) | Semantically related, visually different | Decide: align on whynot's strip OR propose `PipelineStrip` variant upstream |
|
||||||
|
| — | `field_row.html` (vergabe-specific) | n/a | Propose upstream — it's a generic key/value display row |
|
||||||
|
| — | `breadcrumb.html` | n/a | Propose upstream as `Breadcrumb` |
|
||||||
|
| — | `feedback_button.html`, `feedback_modal.html`, `feedback_success.html` | n/a (vergabe-specific UX flow) | Keep vergabe-local; product UI, not DS atoms |
|
||||||
|
| — | `freigabe_modal.html`, `freigabe_success.html` | n/a (vergabe-specific) | Keep vergabe-local |
|
||||||
|
| — | `search_results.html` (HTMX results target) | n/a | Probably vergabe-local, but a `Listbox`/`Combobox` atom could live upstream — defer |
|
||||||
|
|
||||||
|
### Gap summary
|
||||||
|
|
||||||
|
- **5 net-new atoms** in vergabe (Eyebrow, Stamp, PageHeader, Icon wrapper, PipelineStrip).
|
||||||
|
- **4 atoms to align** (Tag ↔ status_badge, Button variants, TopNav, Sidebar).
|
||||||
|
- **2 atoms to propose upstream** (Breadcrumb, FieldRow).
|
||||||
|
- **1 semantic mismatch to resolve** (Stage vs Phase — they're different concepts).
|
||||||
|
- **All vergabe-specific flow UI** (feedback, freigabe, search_results) stays
|
||||||
|
vergabe-local — that's correct, those are product UI, not design system.
|
||||||
|
|
||||||
|
### Components missing from whynot-design — full gap list
|
||||||
|
|
||||||
|
These are components that are absent from `whynot-design` today and would need to
|
||||||
|
land there (or in `whynot-design-django`) before vergabe-teilnahme can fully adopt
|
||||||
|
the system. Grouped by origin.
|
||||||
|
|
||||||
|
#### Already exists in vergabe-teilnahme — candidates to promote upstream
|
||||||
|
|
||||||
|
1. **`Breadcrumb`** — vergabe's `breadcrumb.html`. Trivially generic; no
|
||||||
|
vergabe-specific semantics.
|
||||||
|
2. **`FieldRow`** — vergabe's `field_row.html` (label + value, 3-column grid). The
|
||||||
|
pattern recurs across detail pages; clearly a DS atom.
|
||||||
|
3. **`PhaseDot` / `PhaseNav`** *(name TBD)* — vergabe's `phase_nav.html`.
|
||||||
|
Semantically distinct from whynot's `StageDot` (numbered phases with
|
||||||
|
todo / active / done / warn states, not S0–S4 signal levels). Either upstream
|
||||||
|
as a sibling component, or kept vergabe-local. **Open decision.**
|
||||||
|
|
||||||
|
#### Doesn't exist anywhere yet, but the DS clearly needs them
|
||||||
|
|
||||||
|
These are components that vergabe-teilnahme has as raw Tailwind classes or ad-hoc
|
||||||
|
markup, and whynot-design has no equivalent — but any non-trivial app needs them,
|
||||||
|
so they're real DS gaps:
|
||||||
|
|
||||||
|
4. **`Card`** — whynot's house rules reference cards ("no shadows on cards,"
|
||||||
|
"0–4px radii for cards/sheets") but there is no `Card` JSX component. Vergabe
|
||||||
|
has `.card` as a Tailwind class. **Surprising omission given the explicit
|
||||||
|
design rules.**
|
||||||
|
5. **`Input` / `Textarea` / `Select`** — whynot ships no form primitives at all.
|
||||||
|
Vergabe has `.form-input` and `.form-label` CSS classes. Required before any
|
||||||
|
form-based whynot artefact ships.
|
||||||
|
6. **`Modal` / `Dialog`** — whynot ships none. Vergabe has two (`freigabe_modal`,
|
||||||
|
`feedback_modal`). Whynot's house rules even prescribe modal radius (8px),
|
||||||
|
confirming the intent — just the component is missing.
|
||||||
|
7. **`Table`** — whynot ships none. Vergabe has `.table-base`, `.table-header`,
|
||||||
|
`.table-row` classes. Any data-heavy view (likely most of vergabe) needs it.
|
||||||
|
8. **`Toast` / inline success banner** *(name TBD)* — whynot ships none. Vergabe
|
||||||
|
has `freigabe_success.html` and `feedback_success.html` as ad-hoc partials.
|
||||||
|
Even with whynot's quiet voice, success / error states need a defined visual.
|
||||||
|
|
||||||
|
#### Worth flagging but defer until first real need
|
||||||
|
|
||||||
|
9. **`SearchInput`** — currently inlined inside whynot's `TopNav`. Pulling it out
|
||||||
|
as a standalone atom would be useful (vergabe's `search_results.html` is a
|
||||||
|
target for an HTMX-driven search box).
|
||||||
|
10. **`EmptyState`** — neither codebase has one; vergabe will need it for empty
|
||||||
|
list views. Worth designing once before either side fills the gap locally.
|
||||||
|
11. **`Tabs`, `Dropdown`, `Tooltip`, `Pagination`, `Avatar`** — common DS atoms;
|
||||||
|
neither side has them. Don't add speculatively; add when the first concrete
|
||||||
|
use case appears.
|
||||||
|
|
||||||
|
**Count:** 3 vergabe-existing to promote, 5 genuine DS-level gaps, 5 deferred.
|
||||||
|
The 5 "genuine DS-level gaps" — especially `Card`, `Input`, `Modal`, `Table` — are
|
||||||
|
**blockers for adoption**: vergabe can't replace its current chrome without them
|
||||||
|
existing somewhere shared.
|
||||||
|
|
||||||
|
### Stylistic gaps to address before "done"
|
||||||
|
|
||||||
|
- Vergabe currently uses Tailwind utility classes pervasively
|
||||||
|
(`.btn-primary { @apply … }`); whynot uses inline-style CSS-variable assignment.
|
||||||
|
The Django port should commit to one — recommend CSS variable + utility classes
|
||||||
|
(re-derive whynot's component styles as Tailwind `@apply` blocks that read from
|
||||||
|
CSS vars), so HTMX-injected fragments don't need their own style scaffolding.
|
||||||
|
- Lucide icons aren't wired into vergabe. Need a base.html script tag + an icon partial.
|
||||||
|
- Font stack mismatch: vergabe is `ui-sans-serif`; whynot is IBM Plex Sans / Mono /
|
||||||
|
Serif. Importing whynot's CSS handles this — but it pulls Google Fonts at runtime.
|
||||||
|
Decide self-host vs. CDN.
|
||||||
|
- Vergabe's brand blue (`#3b5bdb`) has to go entirely. No mid-state — the whynot
|
||||||
|
aesthetic forbids it.
|
||||||
|
|
||||||
|
## 7. Recommendation and open decision
|
||||||
|
|
||||||
|
**Recommendation:** Strategy B (parallel `whynot-design-django` repo) as the
|
||||||
|
immediate move, with the README explicitly framing it as a **bridge** that becomes
|
||||||
|
obsolete if whynot-design eventually pivots to Lit web components. Concretely this
|
||||||
|
means **three workplans**, not one:
|
||||||
|
|
||||||
|
1. **`whynot-design`**: small additions — tag v0.1.0, add upstream candidates
|
||||||
|
(`Breadcrumb`, `FieldRow`), document the parity contract for downstream Django port.
|
||||||
|
2. **`whynot-design-django`** (new repo): bootstrap, ship v0.1.0 with the 11
|
||||||
|
components + 2 vergabe-contributed atoms, set up token-sync + parity tests.
|
||||||
|
3. **`vergabe-teilnahme`** (`WP-0017`): consume `whynot-design-django`, retheme,
|
||||||
|
pilot on one page first, then full sweep.
|
||||||
|
|
||||||
|
**Open decision (blocks workplan drafting):**
|
||||||
|
|
||||||
|
Strategy A (pivot to Lit immediately) vs. Strategy B (parallel Django repo) vs.
|
||||||
|
"B now, A later" — Bernd to choose. If "B now, A later," add a workplan stub for
|
||||||
|
the Lit pivot in `whynot-design` itself so it doesn't get forgotten. If "A from the
|
||||||
|
start," the Django repo doesn't exist and the workplans collapse to two.
|
||||||
|
|
||||||
|
## Sources
|
||||||
|
|
||||||
|
- [Shoelace / Web Awesome](https://shoelace.style/) — framework-agnostic web components DS
|
||||||
|
- [Lit + Web Components for cross-framework UIs](https://thenewstack.io/how-to-build-framework-agnostic-uis-with-web-components/)
|
||||||
|
- [HTMX + Shoelace example](https://binaryigor.com/htmx-with-shoelace-framework-agnostic-components-in-an-example-app.html)
|
||||||
|
- [W3C Design Tokens spec first stable version (Oct 2025)](https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/)
|
||||||
|
- [Style Dictionary cross-platform tokens](https://styledictionary.com/info/tokens/)
|
||||||
|
- [Django Cotton — HTML-like component syntax](https://django-cotton.com/)
|
||||||
|
- [django-bird](https://github.com/joshuadavidthomas/django-bird)
|
||||||
|
- [Salesforce — Beyond Components: multi-framework DS](https://medium.com/salesforce-ux/beyond-components-a-design-system-to-support-multiple-frameworks-cb1e4d511f66)
|
||||||
|
- [AgnosticUI post-mortem (rewrite to Lit)](https://frontendmasters.com/blog/post-mortem-rewriting-agnosticui-with-lit-web-components/)
|
||||||
398
workplans/WP-0017-whynot-design-tokens.md
Normal file
398
workplans/WP-0017-whynot-design-tokens.md
Normal file
@@ -0,0 +1,398 @@
|
|||||||
|
---
|
||||||
|
id: WP-0017
|
||||||
|
title: whynot-design Adoption — Phase 1 (Tokens + CSS)
|
||||||
|
status: ready
|
||||||
|
phase: 17-of-n
|
||||||
|
created: "2026-05-23"
|
||||||
|
depends_on: WP-0016
|
||||||
|
---
|
||||||
|
|
||||||
|
# WP-0017 — whynot-design Adoption · Phase 1 (Tokens + CSS)
|
||||||
|
|
||||||
|
Übernahme des `whynot-design`-Systems
|
||||||
|
(`~/whynot-design`, gitea `whynot/whynot-design`) in vergabe-teilnahme in
|
||||||
|
**Phase 1: Tokens + CSS-Variablen**. Keine Komponenten-Portierung. Bestehende
|
||||||
|
Django-Partials und Tailwind-Komponentenklassen bleiben markup-seitig unverändert
|
||||||
|
und werden durch den CSS-Variablen-Tausch automatisch retoniert.
|
||||||
|
|
||||||
|
**Strategiebeschluss vom 2026-05-23:** zweistufige Adoption.
|
||||||
|
- Phase 1 (dieser Workplan): nur Tokens + CSS. whynot-spezifische Komponenten
|
||||||
|
(Lit Web Components) sind upstream in Arbeit und werden separat adoptiert.
|
||||||
|
- Phase 2 (eigener Workplan, kommt später): Komponenten-Adoption sobald
|
||||||
|
whynot-design die fehlenden Atome (`Card`, `Modal`, `Input`, `Table`, `Toast`)
|
||||||
|
als Lit Web Components ausliefert.
|
||||||
|
|
||||||
|
**Hintergrund:** ausführliche Analyse der Strategie-Optionen, Komponenten-
|
||||||
|
Inventar und Lücken-Liste in
|
||||||
|
`history/2026-05-23-whynot-design-cross-framework-analysis.md`.
|
||||||
|
|
||||||
|
**Designentscheidungen für Phase 1:**
|
||||||
|
- Distribution: **Vendoring** über Sync-Skript (kein npm/gitea SSH im Docker-Build).
|
||||||
|
- Rollout: **Big-Bang** — eine PR ersetzt die komplette `brand-*`-Palette
|
||||||
|
vergabe-weit. Markup-Änderungen sind nicht erforderlich.
|
||||||
|
- `btn-danger`: **Off-Spec-Rot** behalten (lokale `--danger`-Variable), bis
|
||||||
|
whynot-design eine kanonische Lösung definiert.
|
||||||
|
|
||||||
|
**Pinned upstream:** commit `9419f166ce395858f55b10a5c72268a1fe9fc9d2`
|
||||||
|
(Stand 2026-05-23; einziger Commit im whynot-design-Repo).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: WP-0017-T01
|
||||||
|
title: Vendor-Sync-Skript + initiale Vendor-Übernahme
|
||||||
|
status: todo
|
||||||
|
|
||||||
|
Ziel: deterministisches Pull der whynot-design CSS-/Token-Quellen aus einem
|
||||||
|
gepinnten Commit nach `static/src/vendor/whynot-design/`, ohne Docker-Build
|
||||||
|
SSH-Zugang zu gitea zu geben.
|
||||||
|
|
||||||
|
**`scripts/sync-whynot-design.sh`** — neu anlegen:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
# Synchronisiert die Vendor-Kopie des whynot-Design-Systems aus einem gepinnten
|
||||||
|
# Upstream-Commit. Quelle: ~/whynot-design (Worktree) oder Klone aus gitea.
|
||||||
|
#
|
||||||
|
# Aufruf: ./scripts/sync-whynot-design.sh [<commit-or-ref>]
|
||||||
|
# Default: liest .whynot-design-ref aus dem Vendor-Verzeichnis.
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||||
|
VENDOR_DIR="$ROOT/static/src/vendor/whynot-design"
|
||||||
|
REF_FILE="$VENDOR_DIR/.whynot-design-ref"
|
||||||
|
SRC_REPO="${WHYNOT_DESIGN_SRC:-$HOME/whynot-design}"
|
||||||
|
|
||||||
|
REF="${1:-}"
|
||||||
|
if [[ -z "$REF" && -f "$REF_FILE" ]]; then
|
||||||
|
REF="$(cat "$REF_FILE")"
|
||||||
|
fi
|
||||||
|
if [[ -z "$REF" ]]; then
|
||||||
|
echo "Usage: $0 <commit-or-ref> (or write a ref to $REF_FILE)" >&2
|
||||||
|
exit 2
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [[ ! -d "$SRC_REPO/.git" ]]; then
|
||||||
|
echo "Quelle nicht gefunden: $SRC_REPO" >&2
|
||||||
|
echo "Setze WHYNOT_DESIGN_SRC oder klone gitea:whynot/whynot-design dorthin." >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
mkdir -p "$VENDOR_DIR/tokens"
|
||||||
|
git -C "$SRC_REPO" show "$REF:src/styles/colors_and_type.css" \
|
||||||
|
> "$VENDOR_DIR/colors_and_type.css"
|
||||||
|
for f in colors.json type.json spacing.json index.json; do
|
||||||
|
git -C "$SRC_REPO" show "$REF:tokens/$f" > "$VENDOR_DIR/tokens/$f"
|
||||||
|
done
|
||||||
|
git -C "$SRC_REPO" rev-parse "$REF" > "$REF_FILE"
|
||||||
|
|
||||||
|
echo "Vendor synced → $VENDOR_DIR (ref: $(cat "$REF_FILE"))"
|
||||||
|
```
|
||||||
|
|
||||||
|
Ausführbar machen + initial syncen:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
chmod +x scripts/sync-whynot-design.sh
|
||||||
|
./scripts/sync-whynot-design.sh 9419f166ce395858f55b10a5c72268a1fe9fc9d2
|
||||||
|
```
|
||||||
|
|
||||||
|
Erwartetes Resultat: `static/src/vendor/whynot-design/colors_and_type.css`,
|
||||||
|
`tokens/*.json`, `.whynot-design-ref` mit dem Commit-Hash.
|
||||||
|
|
||||||
|
**`Makefile`** — Target ergänzen:
|
||||||
|
|
||||||
|
```make
|
||||||
|
.PHONY: sync-whynot-design
|
||||||
|
sync-whynot-design:
|
||||||
|
./scripts/sync-whynot-design.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Commit-Hygiene: der Vendor-Inhalt wird **eingecheckt** (kein `.gitignore`).
|
||||||
|
Diffs gegen den Vendor sind Teil des Review-Surfaces beim nächsten Bump.
|
||||||
|
```
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: WP-0017-T02
|
||||||
|
title: CSS-Integration in static/src/main.css
|
||||||
|
status: todo
|
||||||
|
|
||||||
|
Ziel: whynot-Tokens werden global verfügbar, Tailwind-`@theme`-Mapping
|
||||||
|
exponiert sie als Utility-Klassen, vergabe-spezifisches Brand-Blau entfällt.
|
||||||
|
|
||||||
|
**`static/src/main.css`** — vollständig ersetzen (Reihenfolge ist wichtig:
|
||||||
|
whynot-CSS vor Tailwind, damit `@import url(...)` für IBM Plex am Anfang der
|
||||||
|
generierten Datei landet):
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* whynot-design Tokens & semantische Element-Styles (gepinnt via
|
||||||
|
scripts/sync-whynot-design.sh; siehe .whynot-design-ref). */
|
||||||
|
@import "./vendor/whynot-design/colors_and_type.css";
|
||||||
|
|
||||||
|
@import "tailwindcss";
|
||||||
|
|
||||||
|
/* Tailwind v4 scannt diese Pfade für Utility-Klassen. Muss synchron mit
|
||||||
|
der Dockerfile `assets`-Stage bleiben. */
|
||||||
|
@source "../../vergabe_teilnahme/templates";
|
||||||
|
|
||||||
|
/* whynot-Tokens → Tailwind-Theme.
|
||||||
|
Erlaubt: bg-paper, text-ink, border-line, bg-paper-2, text-ink-3, … */
|
||||||
|
@theme {
|
||||||
|
--color-ink: var(--ink);
|
||||||
|
--color-ink-2: var(--ink-2);
|
||||||
|
--color-ink-3: var(--ink-3);
|
||||||
|
--color-ink-4: var(--ink-4);
|
||||||
|
--color-ink-5: var(--ink-5);
|
||||||
|
--color-line: var(--line);
|
||||||
|
--color-line-strong: var(--line-strong);
|
||||||
|
--color-line-soft: var(--line-soft);
|
||||||
|
--color-paper: var(--paper);
|
||||||
|
--color-paper-2: var(--paper-2);
|
||||||
|
--color-paper-3: var(--paper-3);
|
||||||
|
--color-hi: var(--hi);
|
||||||
|
--color-hi-2: var(--hi-2);
|
||||||
|
--color-hi-ink: var(--hi-ink);
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Off-Spec — vergabe-lokal, bis whynot-design eine kanonische destruktive
|
||||||
|
Farbe definiert. Siehe history/2026-05-23-whynot-design-cross-framework-analysis.md
|
||||||
|
§4 "btn-danger". */
|
||||||
|
:root {
|
||||||
|
--danger: #B22222;
|
||||||
|
--danger-fg: #FFFFFF;
|
||||||
|
}
|
||||||
|
|
||||||
|
@layer base {
|
||||||
|
html {
|
||||||
|
font-family: var(--ff-sans, ui-sans-serif), system-ui, sans-serif;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@layer components {
|
||||||
|
/* Karten / Sheets — whynot: ohne Shadow, hairline border */
|
||||||
|
.card { @apply bg-paper rounded border border-line p-6; }
|
||||||
|
|
||||||
|
/* Buttons — whynot: 3 Varianten + off-spec danger */
|
||||||
|
.btn-primary { @apply bg-ink text-paper px-4 py-2 rounded hover:bg-ink-2 transition-colors; }
|
||||||
|
.btn-secondary { @apply bg-paper text-ink border border-line px-4 py-2 rounded hover:bg-paper-2 transition-colors; }
|
||||||
|
.btn-ghost { @apply text-ink-3 px-3 py-2 rounded hover:bg-paper-2; }
|
||||||
|
.btn-danger { background: var(--danger); color: var(--danger-fg); @apply px-4 py-2 rounded transition-colors; }
|
||||||
|
.btn-danger:hover { filter: brightness(0.92); }
|
||||||
|
|
||||||
|
/* Field-Row — Label/Value Grid */
|
||||||
|
.field-row { @apply grid grid-cols-3 gap-4 py-3 border-b border-line-soft last:border-0; }
|
||||||
|
.field-label { @apply text-sm font-medium text-ink-3 col-span-1; }
|
||||||
|
.field-value { @apply text-sm text-ink col-span-2; }
|
||||||
|
|
||||||
|
/* Phasen-Indikatoren — vergabe-Semantik (todo/active/done/warn), in
|
||||||
|
whynot-Palette übersetzt. `phase-warn` nutzt `--hi` (annotation yellow). */
|
||||||
|
.phase-badge { @apply inline-flex items-center justify-center w-7 h-7 rounded-full text-sm font-bold; }
|
||||||
|
.phase-todo { @apply inline-flex items-center justify-center w-7 h-7 rounded-full text-sm font-bold bg-paper-3 text-ink-4; }
|
||||||
|
.phase-active { @apply inline-flex items-center justify-center w-7 h-7 rounded-full text-sm font-bold bg-ink text-paper; }
|
||||||
|
.phase-done { @apply inline-flex items-center justify-center w-7 h-7 rounded-full text-sm font-bold bg-ink-3 text-paper; }
|
||||||
|
.phase-warn { background: var(--hi); color: var(--hi-ink); @apply inline-flex items-center justify-center w-7 h-7 rounded-full text-sm font-bold; }
|
||||||
|
|
||||||
|
/* Titel / Sektionen */
|
||||||
|
.section-title { @apply text-base font-semibold text-ink mb-4; }
|
||||||
|
.page-title { @apply text-2xl font-medium text-ink tracking-tight; }
|
||||||
|
|
||||||
|
/* Formulare */
|
||||||
|
.form-input { @apply w-full rounded border border-line px-3 py-2 text-sm bg-paper focus:outline-none focus:border-ink transition-colors; }
|
||||||
|
.form-label { @apply block text-sm font-medium text-ink-2 mb-1; }
|
||||||
|
|
||||||
|
/* Tabellen */
|
||||||
|
.table-base { @apply w-full text-sm text-left; }
|
||||||
|
.table-header { @apply bg-paper-2 text-ink-3 font-medium text-xs uppercase tracking-wide; }
|
||||||
|
.table-row { @apply border-t border-line-soft hover:bg-paper-2 transition-colors; }
|
||||||
|
|
||||||
|
/* Sidebar */
|
||||||
|
.sidebar-link { @apply flex items-center px-3 py-2 rounded text-sm text-ink-2 hover:bg-paper-2 transition-colors; }
|
||||||
|
.sidebar-link-active { @apply bg-paper text-ink font-medium; box-shadow: inset 0 0 0 1px var(--line); }
|
||||||
|
.sidebar-section-btn { @apply w-full flex items-center justify-between px-3 py-2 text-xs font-semibold text-ink-4 uppercase tracking-wide hover:text-ink-2; }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Kommentar zu Border-Radii:** whynot-Hausregel verlangt 0–4px für Cards/Sheets,
|
||||||
|
8px nur für große Modale. Tailwind `rounded` (= 4px) erfüllt das. Keine
|
||||||
|
`rounded-xl`/`rounded-lg` mehr in den Komponenten-Klassen.
|
||||||
|
|
||||||
|
**Kommentar zu Shadows:** whynot-Regel "no shadows on cards". `shadow-sm` wurde
|
||||||
|
aus `.card` entfernt; Sidebar-Active nutzt `inset` border statt Schatten.
|
||||||
|
|
||||||
|
**Kommentar zu Fonts:** `colors_and_type.css` zieht IBM Plex via
|
||||||
|
`@import url("https://fonts.googleapis.com/...")`. Build-Container und Browser
|
||||||
|
brauchen Internet-Zugriff zu Google Fonts. Für air-gapped Deployment muss das
|
||||||
|
später durch self-hosting ersetzt werden — ist heute nicht relevant
|
||||||
|
(coulombcore k3s hat Internet-Egress).
|
||||||
|
```
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: WP-0017-T03
|
||||||
|
title: Base-Template — Body-Hintergrund auf whynot-Palette
|
||||||
|
status: todo
|
||||||
|
|
||||||
|
**`vergabe_teilnahme/templates/base.html`** — Body-Klasse anpassen:
|
||||||
|
|
||||||
|
```diff
|
||||||
|
- <body class="bg-slate-50 min-h-screen">
|
||||||
|
+ <body class="bg-paper-2 min-h-screen text-ink">
|
||||||
|
```
|
||||||
|
|
||||||
|
Damit der Default-Text vom whynot-Ink-Ton kommt und der Canvas auf Sheet-Beige
|
||||||
|
(`#FAFAF7`) liegt, nicht auf Slate-Blau-50.
|
||||||
|
|
||||||
|
Keine weiteren Markup-Änderungen in Phase 1. Alle `bg-slate-*`/`text-slate-*`
|
||||||
|
Utilities in den Page-Templates werden in T05 (Smoke-Test) gesichtet und nur
|
||||||
|
dann gepatcht, wenn sie visuell brechen — Tailwinds Slate-Skala existiert
|
||||||
|
weiterhin parallel zur whynot-Palette.
|
||||||
|
```
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: WP-0017-T04
|
||||||
|
title: Build + Static-Asset-Prüfung
|
||||||
|
status: todo
|
||||||
|
|
||||||
|
Lokaler Build:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm ci
|
||||||
|
npm run build
|
||||||
|
ls -lh static/dist/main.css
|
||||||
|
```
|
||||||
|
|
||||||
|
Erwartet: `main.css` enthält die whynot-CSS-Variablen am Anfang, gefolgt von
|
||||||
|
generierten Tailwind-Utilities. Größe steigt moderat (whynot-CSS ≈ 8 KB
|
||||||
|
unkompressed).
|
||||||
|
|
||||||
|
**Sanity-Check** der generierten Utilities:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grep -c "bg-ink\|bg-paper\|text-ink\|border-line" static/dist/main.css
|
||||||
|
# Erwartet: > 0 (Beweis, dass @theme-Mapping aktiv ist)
|
||||||
|
grep -c "color-brand-500\|3b5bdb" static/dist/main.css
|
||||||
|
# Erwartet: 0 (Alt-Palette komplett raus)
|
||||||
|
```
|
||||||
|
|
||||||
|
Falls eine vergabe-Template-Datei noch `bg-brand-*` o.ä. nutzt: in T05
|
||||||
|
adressieren (visueller Bruch wird dort sichtbar).
|
||||||
|
```
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: WP-0017-T05
|
||||||
|
title: Big-Bang Smoke-Test — visueller Durchlauf aller Hauptseiten
|
||||||
|
status: todo
|
||||||
|
|
||||||
|
Dev-Server starten und durch die wichtigsten Views klicken. Bei jedem visuellen
|
||||||
|
Bruch (Kontrast, weiße Schrift auf weißem Grund, harte Farb-Fremdkörper) eine
|
||||||
|
kurze Notiz machen und im selben Task patchen.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker-compose -f docker-compose.dev.yml up -d
|
||||||
|
# oder: uv run python manage.py runserver
|
||||||
|
```
|
||||||
|
|
||||||
|
Zu prüfende Views (Mindestliste — Anordnung folgt der Sidebar):
|
||||||
|
|
||||||
|
- [ ] Dashboard / Ausschreibungs-Übersicht
|
||||||
|
- [ ] Ausschreibung Detail (Phasen-Nav sichtbar)
|
||||||
|
- [ ] Lose-Liste + Detail
|
||||||
|
- [ ] Aufgaben-Liste
|
||||||
|
- [ ] Dokumente-Übersicht
|
||||||
|
- [ ] Preise-Auswertung
|
||||||
|
- [ ] Partner-Bibliothek
|
||||||
|
- [ ] Marktbegleiter
|
||||||
|
- [ ] Nachbetrachtung
|
||||||
|
- [ ] Feedback-Modal (Trigger via Bug-Button)
|
||||||
|
- [ ] Freigabe-Modal (auf einem freigabefähigen Objekt)
|
||||||
|
- [ ] Search-Results (HTMX-Suche in der Top-Bar)
|
||||||
|
|
||||||
|
**Typische Brüche, die zu erwarten sind:**
|
||||||
|
|
||||||
|
1. Direkt im Template inline gesetzte `bg-blue-*`, `text-blue-*`, `bg-brand-*` —
|
||||||
|
in den whynot-Äquivalenten ersetzen (`bg-ink`, `text-ink`, `bg-hi`).
|
||||||
|
2. `shadow-sm`/`shadow-md` auf Cards — entfernen (whynot-Regel: keine Shadows
|
||||||
|
auf Cards, nur auf Popovers).
|
||||||
|
3. `rounded-lg`/`rounded-xl` auf nicht-Modal-Elementen — auf `rounded` (=4px)
|
||||||
|
reduzieren.
|
||||||
|
4. Fokus-Ringe in Brand-Blau — der `.form-input`-Style nutzt jetzt Border-Ink;
|
||||||
|
Tailwind-Default-Ring kann noch blau sein, ggf. globalen Ring-Reset
|
||||||
|
ergänzen.
|
||||||
|
|
||||||
|
Screenshots der Hauptseiten **vor und nach** dem Swap in
|
||||||
|
`history/2026-05-23-whynot-design-phase1-screenshots/` ablegen, als
|
||||||
|
Sichtprüfungs-Beleg.
|
||||||
|
```
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: WP-0017-T06
|
||||||
|
title: Doku-Update und Phase-2-Pflock
|
||||||
|
status: todo
|
||||||
|
|
||||||
|
**`wiki/`** — neue Datei `wiki/DesignSystem.md` mit knappem Inhalt:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Design System
|
||||||
|
|
||||||
|
vergabe-teilnahme nutzt das `whynot-design`-System
|
||||||
|
(gitea `whynot/whynot-design`) als visuelle Basis.
|
||||||
|
|
||||||
|
**Phase 1 (aktuell, ab WP-0017):** nur Tokens + CSS-Variablen, vendoring nach
|
||||||
|
`static/src/vendor/whynot-design/`. Sync via `make sync-whynot-design`. Aktuell
|
||||||
|
gepinnter Commit: siehe `static/src/vendor/whynot-design/.whynot-design-ref`.
|
||||||
|
|
||||||
|
**Phase 2 (offen):** Komponenten-Adoption sobald upstream Lit Web Components
|
||||||
|
und die fehlenden Atome (Card, Modal, Input, Table, Toast) ausliefert. Eigener
|
||||||
|
Workplan wird zu diesem Zeitpunkt angelegt.
|
||||||
|
|
||||||
|
**Lokale Abweichungen** vom whynot-System (dokumentiert in `main.css`):
|
||||||
|
- `btn-danger` mit Off-Spec-Rot (`#B22222`) — whynot definiert keine
|
||||||
|
destruktive Farbe; vergabe-Nutzung erfordert sie für Löschen-Aktionen.
|
||||||
|
Wird zurückgebaut, sobald upstream eine kanonische Lösung definiert.
|
||||||
|
|
||||||
|
**Hintergrund:** Strategie-Analyse + Komponenten-Lücken in
|
||||||
|
`history/2026-05-23-whynot-design-cross-framework-analysis.md`.
|
||||||
|
```
|
||||||
|
|
||||||
|
**`CLAUDE.md` / `.claude/rules/stack-and-commands.md`** — Stack-Eintrag
|
||||||
|
ergänzen um `whynot-design` und den Sync-Befehl:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Stack
|
||||||
|
|
||||||
|
- **Language:** Python 3.12 (Django 6), Node 22 (Vite/Tailwind v4)
|
||||||
|
- **Key deps:** Django, htmx, Alpine.js, Tailwind v4, whynot-design (vendored)
|
||||||
|
|
||||||
|
## Dev Commands
|
||||||
|
|
||||||
|
…
|
||||||
|
# Design-System-Vendor aktualisieren (whynot-design Pin bumpen)
|
||||||
|
make sync-whynot-design
|
||||||
|
```
|
||||||
|
|
||||||
|
**Workplan-Index** in `workplans/README.md` ist bereits 12-Workplan-zentriert
|
||||||
|
und veraltet (es gibt jetzt 17). Nicht in diesem WP anpassen — eigener
|
||||||
|
Aufräum-WP, falls der Index wieder verbindlich werden soll.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Nicht in diesem Workplan
|
||||||
|
|
||||||
|
- Komponenten-Portierung (React-JSX → Django-Partials) — entfällt; wird durch
|
||||||
|
upstream Lit Web Components in Phase 2 obsolet.
|
||||||
|
- `whynot-design-django`-Repo — entfällt aus dem gleichen Grund.
|
||||||
|
- Neue Atome (Card, Modal, Input, Table, Toast als DS-Komponenten) — kommen
|
||||||
|
upstream; bis dahin vergabe-lokal über Tailwind-Klassen.
|
||||||
|
- Visuelle Regression-Tests (Playwright) — wäre sinnvoll, aber nicht
|
||||||
|
Voraussetzung für Phase 1.
|
||||||
|
- Markup-Änderungen in Page-Templates über das in T05 Notwendige hinaus.
|
||||||
|
|
||||||
|
## Definition of Done
|
||||||
|
|
||||||
|
- `static/src/vendor/whynot-design/colors_and_type.css` vorhanden,
|
||||||
|
`.whynot-design-ref` enthält gepinnten Commit-Hash.
|
||||||
|
- `npm run build` erfolgreich, `static/dist/main.css` ohne `#3b5bdb`
|
||||||
|
(Alt-Brand-Blau) und mit aktiven `bg-ink`/`bg-paper`-Utilities.
|
||||||
|
- Alle 12 Smoke-Test-Views in T05 visuell durchgegangen, Brüche gepatcht,
|
||||||
|
Screenshots in `history/` abgelegt.
|
||||||
|
- `wiki/DesignSystem.md` existiert und referenziert History-Artefakt +
|
||||||
|
Phase-2-Bedingung.
|
||||||
Reference in New Issue
Block a user