geneseed 5.5.0 → 5.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +24 -0
- package/README.md +9 -9
- package/SHIPPED.md +1 -1
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/foreman-mode.md +1 -1
- package/docs/concepts/hooks.md +1 -1
- package/docs/extending.md +1 -1
- package/docs/guides/install.md +5 -5
- package/docs/reference/profiles.md +84 -0
- package/harness.config.json +1 -1
- package/js/build/export.mjs +11 -16
- package/js/hosts/hooks.mjs +20 -6
- package/package.json +1 -1
- package/profiles/autonomous.json +14 -0
- package/profiles/corporate.json +14 -0
- package/profiles/mentor.json +13 -0
- package/profiles/minimal.json +15 -0
- package/src/agents/devops-engineer.md +6 -5
- package/src/agents/kubernetes-specialist.md +3 -1
- package/src/agents/spring-boot-engineer.md +3 -3
- package/src/agents/spring-reviewer.md +4 -2
- package/src/skills/codebase-design.md +2 -2
- package/src/skills/commit.md +4 -0
- package/src/skills/diagram-design/SKILL.md +12 -7
- package/src/skills/diagram-design/VENDOR.md +19 -14
- package/src/skills/diagram-design/references/layout-budget.md +7 -1
- package/src/skills/diagram-design/references/onboarding.md +1 -1
- package/src/skills/diagram-design/references/primitives-core.md +1 -1
- package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
- package/src/skills/diagram-design/references/style-guide.md +1 -1
- package/src/skills/diagram-design/references/type-dependency.md +69 -0
- package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
- package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
- package/src/skills/diagram-design/references/type-sbgn.md +80 -0
- package/src/skills/diagram-design/references/type-scatter.md +1 -1
- package/src/skills/diagram-design/references/type-steps.md +180 -0
- package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
- package/src/skills/geneseed-code-review.md +2 -1
- package/src/skills/parallel-agents.md +1 -1
- package/src/skills/react-view-transitions/AGENTS.md +26 -26
- package/src/skills/react-view-transitions/SKILL.md +1 -1
- package/src/skills/react-view-transitions/VENDOR.md +12 -3
- package/src/skills/spring-boot/cloud.md +19 -1
- package/src/skills/spring-boot/logging.md +5 -3
- package/src/skills/spring-boot/web.md +27 -2
- package/src/skills/spring-boot.md +4 -2
- package/src/skills/spring-data-jpa.md +18 -4
- package/src/skills/spring-testing.md +4 -0
- package/src/upstreams.json +4 -4
- package/web/dist/assets/{Activity-LKsDzsnK.js → Activity-bUSPM3Dl.js} +1 -1
- package/web/dist/assets/{ActivityDetail-DhwTfPm6.js → ActivityDetail-AHRoXeFN.js} +1 -1
- package/web/dist/assets/{Bonsai-CePMLrpr.js → Bonsai-B5XY9pid.js} +1 -1
- package/web/dist/assets/{CopyButton-CuoaJ6k7.js → CopyButton-C0wwRR9H.js} +1 -1
- package/web/dist/assets/{Dashboard-D1VKuvLe.js → Dashboard-DPAA96EI.js} +2 -2
- package/web/dist/assets/{Docs-CUrHJKaU.js → Docs-CpGDq165.js} +1 -1
- package/web/dist/assets/{Factories-Ci1XfmSy.js → Factories-cNhETa5Q.js} +1 -1
- package/web/dist/assets/{GreenhouseView-CNfH2lPK.js → GreenhouseView-DO3ADmT9.js} +1 -1
- package/web/dist/assets/{Installs-ZHQZM1iS.js → Installs-D3dDyq10.js} +1 -1
- package/web/dist/assets/{JournalView-CMsWahkS.js → JournalView--W-Lw_V9.js} +1 -1
- package/web/dist/assets/{Kits-CkliyK0n.js → Kits-ChfehxY6.js} +1 -1
- package/web/dist/assets/Laws-CNxYmV36.js +4 -0
- package/web/dist/assets/{LibRows-Brv0Hmkr.js → LibRows-CiPvsRYB.js} +1 -1
- package/web/dist/assets/{Library-BYmiLjJr.js → Library-BxQvbwVU.js} +1 -1
- package/web/dist/assets/{Loops-ytm-xJ68.js → Loops-DAblKkyq.js} +1 -1
- package/web/dist/assets/{OperatorHudView-KaqCx_HP.js → OperatorHudView-QtSaSyYm.js} +1 -1
- package/web/dist/assets/{Personal-CmcnRKYE.js → Personal-DxSGv638.js} +1 -1
- package/web/dist/assets/{Settings-tUrpdOfq.js → Settings-CgTbhvRv.js} +1 -1
- package/web/dist/assets/{Tabs-CD7etcGD.js → Tabs-Cf4X1hdz.js} +1 -1
- package/web/dist/assets/{index-COKbhFNo.js → index-B_pTwZra.js} +3 -3
- package/web/dist/assets/index-CzfImiYb.css +1 -0
- package/web/dist/index.html +2 -2
- package/web/dist/assets/Laws-hh4O3HZ4.js +0 -4
- package/web/dist/assets/index-Ba_Kg3Af.css +0 -1
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# Steps
|
|
2
|
+
|
|
3
|
+
**Best for:** a short, ordered sequence of stages where the order is the claim and each stage needs a number, a compact visual cue, a title, and one brief explanation. Use it for methods, playbooks, onboarding paths, launch checklists, and “how it works” explainers.
|
|
4
|
+
|
|
5
|
+
Prefer **Timeline** when spacing encodes real elapsed time, **Flowchart** when the route branches, **Swimlane** when ownership and handoffs matter, and **Process** when each stage must expose actors, tools, or input/output payloads. Steps has one rail, no branches, no time scale, and no actor lanes.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Inputs
|
|
10
|
+
|
|
11
|
+
```yaml
|
|
12
|
+
steps: # 3..7, left to right
|
|
13
|
+
- number: "01"
|
|
14
|
+
title: "Frame"
|
|
15
|
+
description: ["Define the decision", "and its success signal"]
|
|
16
|
+
icon: file # optional; from primitive-icons.md
|
|
17
|
+
- number: "02"
|
|
18
|
+
title: "Research"
|
|
19
|
+
description: ["Gather evidence from", "customers and operators"]
|
|
20
|
+
icon: users
|
|
21
|
+
- number: "03"
|
|
22
|
+
title: "Synthesize"
|
|
23
|
+
description: ["Turn observations into", "one testable direction"]
|
|
24
|
+
icon: search
|
|
25
|
+
focal: true
|
|
26
|
+
- number: "04"
|
|
27
|
+
title: "Decide"
|
|
28
|
+
description: ["Commit the scope and", "name the trade-offs"]
|
|
29
|
+
icon: database
|
|
30
|
+
- number: "05"
|
|
31
|
+
title: "Ship"
|
|
32
|
+
description: ["Release, measure, and", "feed learning forward"]
|
|
33
|
+
icon: container
|
|
34
|
+
dark: false
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Rules:
|
|
38
|
+
|
|
39
|
+
- `steps` contains 3–7 entries. Fewer than three is a list; more than seven needs grouping or a second diagram.
|
|
40
|
+
- Exactly one step is `focal: true`. It is the decision, transformation, or risk the figure exists to emphasize.
|
|
41
|
+
- `number` is two digits for fewer than 100 steps (`01`, `02`, …) so the rail scans evenly.
|
|
42
|
+
- `description` is one or two short lines, each no longer than 26 characters at the standard ramp. Rewrite rather than shrink.
|
|
43
|
+
- `icon` is optional and must come from [`primitive-icons.md`](primitive-icons.md). Omit icons from every step if a coherent set is unavailable; never mix line icons, emoji, and brand marks.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 2. Layout grammar
|
|
48
|
+
|
|
49
|
+
The canonical `doc-wide` canvas is `1280×720`. All structural coordinates sit on the 4px grid.
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
outer_x = 80
|
|
53
|
+
rail_y = 240
|
|
54
|
+
rail_h = 48
|
|
55
|
+
n = len(steps)
|
|
56
|
+
usable_w = 1280 - 2 * outer_x
|
|
57
|
+
stage_w = min(224, 4 * floor(usable_w / (4 * n)))
|
|
58
|
+
content_w = n * stage_w
|
|
59
|
+
start_x = (1280 - content_w) / 2
|
|
60
|
+
stage_x(i) = start_x + i * stage_w
|
|
61
|
+
stage_cx(i) = stage_x(i) + stage_w / 2
|
|
62
|
+
medallion_cy = rail_y + rail_h / 2
|
|
63
|
+
medallion_r = 36
|
|
64
|
+
number_y = 164
|
|
65
|
+
number_rule_y = 184..220
|
|
66
|
+
title_y = 360
|
|
67
|
+
description_y = 388, 408
|
|
68
|
+
legend_rule_y = 600
|
|
69
|
+
legend_y = 636
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
This yields a 224px stage for 3–5 steps, 184px for 6, and 160px for 7. Keep `stage_w` on the 4px grid, center the combined rail, and preserve at least 24px between description columns. If copy does not fit the narrower six- or seven-stage columns, widen the canvas or rewrite the copy; do not reduce the type ramp.
|
|
73
|
+
|
|
74
|
+
### Rail
|
|
75
|
+
|
|
76
|
+
- Draw one contiguous horizontal rail from `stage_x(0)` to `stage_x(n-1) + stage_w`.
|
|
77
|
+
- Each stage owns one `stage_w × 48` segment. Alternate `ink @ 0.05` and `ink @ 0.09` fills to make the segmentation visible without introducing a series palette.
|
|
78
|
+
- The focal segment uses `accent-tint` with a 1px `accent` top and bottom rule.
|
|
79
|
+
- The rail itself expresses order. Do not add arrows between adjacent stages; they duplicate the layout.
|
|
80
|
+
|
|
81
|
+
### Number and guide
|
|
82
|
+
|
|
83
|
+
- Number: `{eyebrow}` role, 8px, weight 600, letter-spacing `0.14em`, centered at `stage_cx(i)`.
|
|
84
|
+
- Guide: 1px vertical rule from `y=184` to `y=220`, `rule-solid`; focal guide uses `accent`.
|
|
85
|
+
- The number is `muted` by default and `accent` for the focal step.
|
|
86
|
+
|
|
87
|
+
### Icon medallion
|
|
88
|
+
|
|
89
|
+
- Circle center `(stage_cx(i), 264)`, radius 36.
|
|
90
|
+
- Draw an opaque `paper` circle first so the rail does not show through, then a 1px outline.
|
|
91
|
+
- Default outline and icon use `ink`; focal outline and icon use `accent` and the circle may use `accent-tint`.
|
|
92
|
+
- Place one 24×24 primitive at `(stage_cx(i)-12, 252)`. Icons are decorative (`aria-hidden="true"`); the accessible name comes from the SVG title and description.
|
|
93
|
+
|
|
94
|
+
### Copy block
|
|
95
|
+
|
|
96
|
+
- Title: `{node-name}` role, 12px, weight 600, centered at `y=360`.
|
|
97
|
+
- Description: `{sublabel}` role, 9px, centered, at most two lines at `y=388` and `y=408`.
|
|
98
|
+
- Titles use `ink`; descriptions use `muted`. The focal title may use `accent`; the description remains `muted`.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 3. Focal and color rules
|
|
103
|
+
|
|
104
|
+
One step is focal. Treat its number, guide, rail segment, medallion outline/icon, and title as one visual unit. All remaining steps stay neutral.
|
|
105
|
+
|
|
106
|
+
Do not assign a different hue to every step. The familiar five-color infographic treatment turns sequence into a legend-reading task and conflicts with the global 1–2 accent rule. If stages genuinely encode categories rather than order, use a chart or another type whose color carries data.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## 4. Legend
|
|
111
|
+
|
|
112
|
+
Use a bottom strip only when the focal state needs explanation. The canonical examples show:
|
|
113
|
+
|
|
114
|
+
- neutral outlined medallion — `Stage`
|
|
115
|
+
- accent outlined medallion — `Focal stage`
|
|
116
|
+
- italic note — `Equal spacing shows order, not elapsed time.`
|
|
117
|
+
|
|
118
|
+
If the title or subtitle already names the focal stage and the distinction is obvious, remove the legend.
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 5. Reproducibility checklist
|
|
123
|
+
|
|
124
|
+
1. Step count is 3–7 and exactly one entry is focal.
|
|
125
|
+
2. Step origins, segment widths, medallion centers, and copy anchors derive from §2.
|
|
126
|
+
3. The rail is contiguous; there are no gaps, arrowheads, or diagonal connectors.
|
|
127
|
+
4. Every medallion has an opaque paper mask beneath its outline.
|
|
128
|
+
5. Every step either has one icon from `primitive-icons.md` or all icons are omitted.
|
|
129
|
+
6. Titles stay at 12px and descriptions at 9px; long copy is rewritten, not shrunk.
|
|
130
|
+
7. The focal step is the only accent-bearing stage.
|
|
131
|
+
8. The SVG uses the accessible SVG contract and the wrapper owns horizontal scrolling.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## 6. What `verify-steps.py` requires
|
|
136
|
+
|
|
137
|
+
The checker reads attributes, so every mark binds itself to its stage and draws exactly what it states.
|
|
138
|
+
|
|
139
|
+
- **Bindings.** Each stage has one rail `<rect data-role="rail">`, one medallion `<circle data-role="medallion">` and one number `<text data-role="number">`, all with the same unique `data-step`. Rails also carry `data-index` 1..n in left-to-right order. Exactly one rail and its medallion carry `data-focal="true"`.
|
|
140
|
+
- **Geometry.** Rails share `y`, `width` and `height` and touch end to end. Medallions are centered on their segment with one shared radius; numbers are centered on it at `x` and print the two-digit index. Every mark stays inside the viewBox.
|
|
141
|
+
- **Allowed attributes.** A rail may carry only `x y width height fill fill-opacity`, a medallion only `cx cy r fill stroke stroke-width`, a number only `x y fill font-size font-weight font-family text-anchor`, plus their `data-*` bindings. No `style`, `class`, `id`, `transform`, `dx`/`dy`, `opacity` or anything else. A number contains only its text.
|
|
142
|
+
- **Groups.** Marks sit only inside plain `<g>` groups of the one root `<svg>`, never inside `defs`, a nested `svg` or any other element. A group above a mark may carry only `aria-hidden fill stroke stroke-width stroke-linecap stroke-linejoin font-family font-size font-weight letter-spacing text-anchor`. No attribute may appear twice on any element.
|
|
143
|
+
- **Paint and type.** The first `<rect>` in the SVG is the paper (`#f5f5f5` light, `#2d3142` dark). Rails fill with a non-paper house ink above zero alpha. Medallion outlines and numbers use a house ink at 0.4 alpha or more. Numbers resolve to font-size 8 or more, a font family starting with Geist, Geist Mono or Instrument Serif, and `text-anchor="middle"`. Strokes are at most 4 wide.
|
|
144
|
+
- **Page and CSS.** Style marks with presentation attributes. Stylesheet rules that can reach the SVG may set only `box-sizing`, `margin`, `padding` and custom properties; nothing may move or hide the diagram. CONTRIBUTING.md lists the page rules in full.
|
|
145
|
+
|
|
146
|
+
A minimal three-stage figure that passes, with the second stage focal:
|
|
147
|
+
|
|
148
|
+
```html
|
|
149
|
+
<svg viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="steps-min-title steps-min-desc">
|
|
150
|
+
<title id="steps-min-title">Plan, build, ship</title>
|
|
151
|
+
<desc id="steps-min-desc">Three equal stages on one rail; build is the focal stage.</desc>
|
|
152
|
+
<rect width="100%" height="100%" fill="#f5f5f5"/>
|
|
153
|
+
<g aria-hidden="true">
|
|
154
|
+
<rect x="304" y="240" width="224" height="48" fill="rgba(45,49,66,0.05)" data-role="rail" data-step="plan" data-index="1"/>
|
|
155
|
+
<rect x="528" y="240" width="224" height="48" fill="rgba(191,69,32,0.08)" data-role="rail" data-step="build" data-index="2" data-focal="true"/>
|
|
156
|
+
<rect x="752" y="240" width="224" height="48" fill="rgba(45,49,66,0.05)" data-role="rail" data-step="ship" data-index="3"/>
|
|
157
|
+
</g>
|
|
158
|
+
<g font-family="'Geist Mono', monospace" font-size="8" font-weight="600" letter-spacing="0.14em" text-anchor="middle">
|
|
159
|
+
<text x="416" y="164" fill="#4f5d75" data-role="number" data-step="plan">01</text>
|
|
160
|
+
<text x="640" y="164" fill="#bf4520" data-role="number" data-step="build">02</text>
|
|
161
|
+
<text x="864" y="164" fill="#4f5d75" data-role="number" data-step="ship">03</text>
|
|
162
|
+
</g>
|
|
163
|
+
<g aria-hidden="true" fill="#f5f5f5" stroke-width="1">
|
|
164
|
+
<circle cx="416" cy="264" r="36" stroke="#2d3142" data-role="medallion" data-step="plan"/>
|
|
165
|
+
<circle cx="640" cy="264" r="36" stroke="none"/>
|
|
166
|
+
<circle cx="640" cy="264" r="36" fill="rgba(191,69,32,0.08)" stroke="#bf4520" data-role="medallion" data-step="build" data-focal="true"/>
|
|
167
|
+
<circle cx="864" cy="264" r="36" stroke="#2d3142" data-role="medallion" data-step="ship"/>
|
|
168
|
+
</g>
|
|
169
|
+
</svg>
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## 7. Anti-patterns
|
|
175
|
+
|
|
176
|
+
- Rainbow stage bands with no categorical meaning.
|
|
177
|
+
- Using Steps for dated events, branching decisions, actor handoffs, or feedback loops.
|
|
178
|
+
- Paragraphs under each stage; two short lines is the ceiling.
|
|
179
|
+
- A different icon style per stage, emoji mixed with line icons, or icons that repeat the title without adding recognition.
|
|
180
|
+
- Arrowheads between every adjacent segment. The left-to-right rail already says “next.”
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Unit Grid
|
|
2
|
+
|
|
3
|
+
**Best for:** one bounded whole expressed as equal, discrete units: completion, capacity, survey responses, inventory, or a checklist. Use the canonical waffle form when the reader needs to see an exact count out of 100.
|
|
4
|
+
|
|
5
|
+
Not for: category-by-category comparison (use a **bar chart**), a part-of-whole with unequal pieces (use a **treemap**), continuous change (use a **line chart**), or a matrix where row and column positions carry meaning (the future punch-card variant).
|
|
6
|
+
|
|
7
|
+
## Input contract
|
|
8
|
+
|
|
9
|
+
```yaml
|
|
10
|
+
title: "Release readiness"
|
|
11
|
+
total: 100
|
|
12
|
+
filled: 64
|
|
13
|
+
unit_label: "release check"
|
|
14
|
+
focal_index: 63
|
|
15
|
+
source_note: "Illustrative checklist"
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Validation rules:
|
|
19
|
+
|
|
20
|
+
1. Version 1 is a 10 by 10 grid with exactly 100 cells.
|
|
21
|
+
2. `total` is exactly `100`; `filled` is an integer from `0` through `100`.
|
|
22
|
+
3. Every cell represents one unit. Do not use fractional cells, scaled cells, or merged cells.
|
|
23
|
+
4. At most one completed cell is focal. Accent is editorial emphasis, never a larger unit.
|
|
24
|
+
5. Cells fill in reading order, left to right and top to bottom. A different order needs an explicit future variant.
|
|
25
|
+
6. Rows and columns carry no category meaning in the canonical waffle form.
|
|
26
|
+
|
|
27
|
+
## Layout conventions
|
|
28
|
+
|
|
29
|
+
- Use a 10 by 10 grid of equal 20px cells with a 4px gutter. The shipped examples begin at `(382, 86)`, making the grid 236px square inside a `1000 × 390` viewBox.
|
|
30
|
+
- Every chart root carries `data-unit-grid="true"`, `data-unit-total="100"`, `data-unit-filled`, `data-unit-rows="10"`, and `data-unit-columns="10"`.
|
|
31
|
+
- Every cell is a `<rect>` with `data-unit-cell="filled"` or `data-unit-cell="empty"` and a unique `data-unit-index` from 0 through 99. `scripts/verify-unit-grid.py` checks count, geometry, indices, the declared filled value, and printed labels.
|
|
32
|
+
- Use one ink fill for completed cells, a quieter paper-relative fill for remaining cells, and no more than one accent completed cell. The count, not color, carries the value. Set each cell's literal fill on the `<rect>` (or a parent `<g>`): completed cells must match the page's `:root` `--ink` or `--accent`, and remaining cells share one other fill well away from both. Cells sit directly in the chart `<svg>` or in plain `<g>`/`<a>` groups with no `style`, `transform` or conditional attributes; cell strokes stay at or under 2px and corner radii at or under a quarter of the cell. The verifier rejects opacity, visibility, display, filter, mask, clip-path, paint-order and mix-blend-mode on cells or their ancestors, paint, stroke or hiding rules in `<style>` (after decoding escapes), `@import`, any linked stylesheet but Google Fonts, SMIL animation, and any element drawn after the first cell whose box touches the grid or cannot be computed from plain numeric attributes. It does not see HTML wrappers around the SVG or scripts.
|
|
33
|
+
- Mark the percentage text with `data-unit-percent="true"` and the count text with `data-unit-count="true"`. They must read `64%` and `64 complete · 36 remaining` for `filled: 64`; both are checked against `data-unit-filled`. Each label is plain visible `<text>` inside the chart SVG (no child elements, no hiding or `style` attributes), painted `--ink` or `--muted`, at least 8px, and inside the viewBox.
|
|
34
|
+
- Do not apply transforms to cells or their SVG/group ancestors, or move geometry through CSS. Bake movement into the coordinates so the verifier checks the rendered positions.
|
|
35
|
+
- Put the exact count in text near the grid and state the unit in the source line. The grid must remain understandable in grayscale.
|
|
36
|
+
- Keep the legend block below the grid. Label the focal cell as editorial emphasis, so it cannot be mistaken for a special unit.
|
|
37
|
+
|
|
38
|
+
## Honest-data rule
|
|
39
|
+
|
|
40
|
+
A unit grid claims that one mark equals one unit. Never round a 63.4% result to 64 filled cells without saying that the display is rounded. Never use a partial fill, larger focal cell, gradient, or area-sized mark to recover precision. If the denominator is not naturally bounded to 100, choose a number of whole cells that makes the unit honest or choose a different chart.
|
|
41
|
+
|
|
42
|
+
## Complexity budget
|
|
43
|
+
|
|
44
|
+
- Exactly 100 cells in a 10 by 10 grid.
|
|
45
|
+
- One count and one optional focal completed cell.
|
|
46
|
+
- One legend and one source note.
|
|
47
|
+
- Static output only.
|
|
48
|
+
- No categorical row or column axes in version 1.
|
|
49
|
+
|
|
50
|
+
## Anti-patterns
|
|
51
|
+
|
|
52
|
+
- Partial, merged, oversized, or differently shaped cells.
|
|
53
|
+
- Rainbow status fills or multiple accent cells.
|
|
54
|
+
- Using the grid for a denominator other than 100 without an explicit future variant.
|
|
55
|
+
- Treating rows and columns as categories. That is the later punch-card variant, not this canonical waffle form.
|
|
56
|
+
- Gradients, heatmap ramps, 3-D treatments, or shadows.
|
|
57
|
+
- Filling in a non-reading order without explaining that order.
|
|
58
|
+
|
|
59
|
+
## Examples
|
|
60
|
+
|
|
61
|
+
- `assets/example-unit-grid.html` - minimal light.
|
|
62
|
+
- `assets/example-unit-grid-dark.html` - minimal dark with the same dataset and geometry.
|
|
63
|
+
- `assets/example-unit-grid-full.html` - full editorial with unchanged grid geometry.
|
|
@@ -21,7 +21,8 @@
|
|
|
21
21
|
4. For a large change, consider dispatching the
|
|
22
22
|
[reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) to keep the main context clean.
|
|
23
23
|
When a spec exists and the diff spans more than a few files, run pass 3 in its own
|
|
24
|
-
subagent,
|
|
24
|
+
subagent — started fresh, never a fork of your own context — handed only the diff
|
|
25
|
+
command and the spec, alongside passes 1–2: a pass
|
|
25
26
|
that has already filled up on code findings stops reading the spec closely, and
|
|
26
27
|
kept apart, one axis's findings never mask the other's.
|
|
27
28
|
5. Pass 1 — correctness: logic errors, edge cases, error handling, race
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
## Procedure
|
|
12
12
|
1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE:one-writer-per-file}}). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
|
|
13
13
|
2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return. Several small edits of one kind (the same fix, constant or field across files) form ONE unit with the union write set and get one review.
|
|
14
|
-
3. Dispatch each unit to its own subagent in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (a unit in the shared tree never commits or pushes; a slice on its own branch (step 6) commits only there, never pushes — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
|
|
14
|
+
3. Dispatch each unit to its own fresh subagent (never a fork: a fork carries your context and model tier) in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (a unit in the shared tree never commits or pushes; a slice on its own branch (step 6) commits only there, never pushes — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
|
|
15
15
|
|
|
16
16
|
**Brief checklist** — the envelope also states:
|
|
17
17
|
- **Git state:** the ref to measure (`HEAD` or `origin/main`, after a fetch) and whether the diff is staged, on disk or committed; after a restart, `git log` before redoing "uncommitted" work — a stale ref redoes every finding.
|
|
@@ -44,7 +44,7 @@ Reserve directional slides for hierarchical navigation (list → detail) and ord
|
|
|
44
44
|
## Availability
|
|
45
45
|
|
|
46
46
|
- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
|
|
47
|
-
- **Without Next.js:**
|
|
47
|
+
- **Without Next.js:** Use stable `react` and `react-dom` 19.3 or newer (`ViewTransition` and `addTransitionType` became stable in React 19.3). Earlier stable React versions do not include these APIs.
|
|
48
48
|
- Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
|
|
49
49
|
|
|
50
50
|
---
|
|
@@ -363,7 +363,7 @@ For each shared element (`name` prop), note every navigation where a pair forms
|
|
|
363
363
|
|
|
364
364
|
## Step 2: Add CSS Recipes
|
|
365
365
|
|
|
366
|
-
Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.
|
|
366
|
+
Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](references/css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.
|
|
367
367
|
|
|
368
368
|
Customize timing after the structure works. Keep ordinary crossfades opacity-only; scope blur to a specific shared morph when it is intentional.
|
|
369
369
|
|
|
@@ -375,7 +375,7 @@ For every persistent element identified in Step 1, add a `viewTransitionName` st
|
|
|
375
375
|
<header style={{ viewTransitionName: "site-header" }}>...</header>
|
|
376
376
|
```
|
|
377
377
|
|
|
378
|
-
Then add the [Persistent Element Isolation](css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround) instead.
|
|
378
|
+
Then add the [Persistent Element Isolation](references/css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround) instead.
|
|
379
379
|
|
|
380
380
|
If a Suspense fallback mirrors a persistent control (e.g., a skeleton search input), give both the real control and the skeleton the same `viewTransitionName` so they morph in place.
|
|
381
381
|
|
|
@@ -410,7 +410,7 @@ Then wrap each **page component** (not layout) in a type-keyed `<ViewTransition>
|
|
|
410
410
|
</ViewTransition>
|
|
411
411
|
```
|
|
412
412
|
|
|
413
|
-
The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
|
|
413
|
+
The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](references/css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
|
|
414
414
|
|
|
415
415
|
Extract this into a reusable component so every page doesn't repeat the verbose type map:
|
|
416
416
|
|
|
@@ -460,7 +460,7 @@ This example uses `slide-down` / `slide-up` for directional vertical motion. For
|
|
|
460
460
|
- Always use `default="none"` on the content `<ViewTransition>` to prevent re-animation on revalidation or unrelated transitions.
|
|
461
461
|
- Use simple string props (not type maps) on Suspense `<ViewTransition>`s — Suspense resolves fire as separate transitions with no type, so type-keyed props won't match.
|
|
462
462
|
- A fallback/content `share` pair morphs between snapshots. Use it only when that interpolation is desired and does not distort layout or geometry.
|
|
463
|
-
- If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](patterns.md#suspense-reveal-flicker).
|
|
463
|
+
- If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](references/patterns.md#suspense-reveal-flicker).
|
|
464
464
|
|
|
465
465
|
## Step 6: Add Shared Element Transitions
|
|
466
466
|
|
|
@@ -478,9 +478,9 @@ For every shared visual element identified in Step 1, add matching named `<ViewT
|
|
|
478
478
|
</ViewTransition>
|
|
479
479
|
```
|
|
480
480
|
|
|
481
|
-
The `share="morph"` class uses the [Shared Element Morph](css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
|
|
481
|
+
The `share="morph"` class uses the [Shared Element Morph](references/css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
|
|
482
482
|
|
|
483
|
-
When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](
|
|
483
|
+
When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](SKILL.md#composing-shared-elements-with-list-identity).
|
|
484
484
|
|
|
485
485
|
**Rules:**
|
|
486
486
|
- Names must be globally unique — use prefixes like `photo-${id}`.
|
|
@@ -497,9 +497,9 @@ Walk through every row in the navigation map from Step 1 and confirm:
|
|
|
497
497
|
- Do persistent elements stay static (not sliding with page content)?
|
|
498
498
|
- Do Suspense reveals animate independently from directional navigations?
|
|
499
499
|
|
|
500
|
-
If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](troubleshooting.md).
|
|
500
|
+
If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](references/troubleshooting.md).
|
|
501
501
|
|
|
502
|
-
For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](nextjs.md).
|
|
502
|
+
For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](references/nextjs.md).
|
|
503
503
|
|
|
504
504
|
---
|
|
505
505
|
|
|
@@ -621,10 +621,10 @@ Use `key` when content identity changes (state resets). Omit for cross-fades (ta
|
|
|
621
621
|
|
|
622
622
|
## Isolate Elements from Parent Animations
|
|
623
623
|
|
|
624
|
-
Pull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](css-recipes.md#persistent-element-isolation)).
|
|
624
|
+
Pull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](references/css-recipes.md#persistent-element-isolation)).
|
|
625
625
|
|
|
626
626
|
- **Persistent chrome** (nav, sidebar, player bar): `<nav style={{ viewTransitionName: 'persistent-nav' }}>` + isolation CSS. `<ViewTransition default="none">` works too, but its auto-name can't take `z-index`/backdrop `display:none` — hand-name when you need those.
|
|
627
|
-
- **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.
|
|
627
|
+
- **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](references/css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.
|
|
628
628
|
- **Naming an interactive element has a cost:** named participants are skipped by hit-testing while a transition runs ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)) — clicks and hover fall through to whatever is beneath. Portal named popovers/menus; rendered inline in a clickable row, mid-transition clicks activate the row and read as outside-clicks that close the popover.
|
|
629
629
|
- **Third-party floating components** (toast libraries, portals you don't render): put the name on an always-mounted wrapper you own — `<div style={{ viewTransitionName: 'toaster' }} className="pointer-events-none fixed inset-0">`. Library containers often unmount when empty, so naming them directly leaves the group unpinned exactly when a toast appears mid-transition. Name a dialog's backdrop separately from its panel so each pins independently.
|
|
630
630
|
|
|
@@ -641,7 +641,7 @@ Don't put a manual `viewTransitionName` on the root DOM node inside `<ViewTransi
|
|
|
641
641
|
|
|
642
642
|
## Sliding Indicator (tabs)
|
|
643
643
|
|
|
644
|
-
One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](nextjs.md#routing-driven-tabs)).
|
|
644
|
+
One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](references/css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)).
|
|
645
645
|
|
|
646
646
|
```tsx
|
|
647
647
|
import { useState, useTransition, ViewTransition } from 'react';
|
|
@@ -668,7 +668,7 @@ export function Tabs({ tabs, indicatorName = 'tab-indicator' }) {
|
|
|
668
668
|
}
|
|
669
669
|
```
|
|
670
670
|
|
|
671
|
-
Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.
|
|
671
|
+
Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.
|
|
672
672
|
|
|
673
673
|
## Layout Displacement Morph
|
|
674
674
|
|
|
@@ -719,7 +719,7 @@ function AnimatedCollapse({ open, children }) {
|
|
|
719
719
|
</Activity>
|
|
720
720
|
```
|
|
721
721
|
|
|
722
|
-
Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](nextjs.md#layout-level-viewtransition)).
|
|
722
|
+
Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](references/nextjs.md#layout-level-viewtransition)).
|
|
723
723
|
|
|
724
724
|
## Exclude Elements with `useOptimistic`
|
|
725
725
|
|
|
@@ -790,9 +790,9 @@ The `types` array (second argument) lets you vary animation based on transition
|
|
|
790
790
|
|
|
791
791
|
**Scrolling hangs while a transition animates:** the `::view-transition` overlay is `position: fixed` and its snapshots don't scroll — a browser limitation, not fixable in React (skipping snaps to the end). Keep reveal durations short; for scroll-driven UI use gesture transitions (experimental `useSwipeTransition`, if available).
|
|
792
792
|
|
|
793
|
-
**Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations).
|
|
793
|
+
**Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations).
|
|
794
794
|
|
|
795
|
-
**Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.
|
|
795
|
+
**Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.
|
|
796
796
|
|
|
797
797
|
**Shared morph silently not firing:** `share` resolved to `none`. Either the VT has `default="none"` with no explicit `share` prop, or `share` is type-keyed and the navigation never adds the type — the link needs `transitionTypes` (or `addTransitionType` in the transition).
|
|
798
798
|
|
|
@@ -800,7 +800,7 @@ The `types` array (second argument) lets you vary animation based on transition
|
|
|
800
800
|
|
|
801
801
|
**An enter animation runs even though Suspense never showed its fallback:** The content-side VT became the topmost entering subtree during navigation. At that call site, add a host DOM element immediately outside `Suspense`. The host suppresses the nested enter during warm navigation but remains mounted so the VT can enter on a later fallback-to-content reveal. Keep the host outside `Suspense`, not inside the reusable crossfade; do nothing when a direct host already exists.
|
|
802
802
|
|
|
803
|
-
**Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](patterns.md#layout-displacement-morph).
|
|
803
|
+
**Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](references/patterns.md#layout-displacement-morph).
|
|
804
804
|
|
|
805
805
|
**`router.back()` and browser back/forward skip the directional slide:** traversals carry no transition types, so type-keyed maps resolve to `default` — untyped shared-element morphs still apply. Use `router.push()` for typed animations.
|
|
806
806
|
|
|
@@ -820,7 +820,7 @@ The `types` array (second argument) lets you vary animation based on transition
|
|
|
820
820
|
|
|
821
821
|
**Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.
|
|
822
822
|
|
|
823
|
-
**Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround).
|
|
823
|
+
**Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround).
|
|
824
824
|
|
|
825
825
|
**`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.
|
|
826
826
|
|
|
@@ -1050,7 +1050,7 @@ The `::view-transition` overlay captures all pointer events. React shrinks it to
|
|
|
1050
1050
|
}
|
|
1051
1051
|
```
|
|
1052
1052
|
|
|
1053
|
-
Trade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)).
|
|
1053
|
+
Trade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)).
|
|
1054
1054
|
|
|
1055
1055
|
---
|
|
1056
1056
|
|
|
@@ -1155,13 +1155,13 @@ Read the current [Next.js View Transitions guide](https://nextjs.org/docs/app/gu
|
|
|
1155
1155
|
|
|
1156
1156
|
Because every link click is a transition, any VT with `default="auto"` fires on **every** navigation — use `default="none"` to prevent competing animations.
|
|
1157
1157
|
|
|
1158
|
-
For unexpected or broken animation behavior, see [troubleshooting.md](troubleshooting.md).
|
|
1158
|
+
For unexpected or broken animation behavior, see [troubleshooting.md](references/troubleshooting.md).
|
|
1159
1159
|
|
|
1160
1160
|
---
|
|
1161
1161
|
|
|
1162
1162
|
## Next.js Implementation Additions
|
|
1163
1163
|
|
|
1164
|
-
When following [implementation.md](implementation.md), apply these additions:
|
|
1164
|
+
When following [implementation.md](references/implementation.md), apply these additions:
|
|
1165
1165
|
|
|
1166
1166
|
**Step 4:** Use `transitionTypes` on `<Link>` — see [The `transitionTypes` Prop](#the-transitiontypes-prop-on-nextlink). If the animation depends on dynamic destination content, also see [When Content Must Be Ready](#when-content-must-be-ready).
|
|
1167
1167
|
|
|
@@ -1171,11 +1171,11 @@ When following [implementation.md](implementation.md), apply these additions:
|
|
|
1171
1171
|
|
|
1172
1172
|
## Layout-Level ViewTransition
|
|
1173
1173
|
|
|
1174
|
-
**Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](
|
|
1174
|
+
**Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](SKILL.md#composing-shared-elements-with-list-identity).
|
|
1175
1175
|
|
|
1176
1176
|
A bare `<ViewTransition>` in layout works only if pages have **no** VTs of their own.
|
|
1177
1177
|
|
|
1178
|
-
**Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](patterns.md#composing-with-activity)).
|
|
1178
|
+
**Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](references/patterns.md#composing-with-activity)).
|
|
1179
1179
|
|
|
1180
1180
|
---
|
|
1181
1181
|
|
|
@@ -1260,15 +1260,15 @@ function SortControl() {
|
|
|
1260
1260
|
}
|
|
1261
1261
|
```
|
|
1262
1262
|
|
|
1263
|
-
List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](patterns.md#searchable-grid-with-usedeferredvalue) pattern.
|
|
1263
|
+
List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](references/patterns.md#searchable-grid-with-usedeferredvalue) pattern.
|
|
1264
1264
|
|
|
1265
|
-
For immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](patterns.md#exclude-elements-with-useoptimistic).
|
|
1265
|
+
For immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](references/patterns.md#exclude-elements-with-useoptimistic).
|
|
1266
1266
|
|
|
1267
1267
|
---
|
|
1268
1268
|
|
|
1269
1269
|
## Routing-Driven Tabs
|
|
1270
1270
|
|
|
1271
|
-
The generalized sliding indicator ([Sliding Indicator](patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.
|
|
1271
|
+
The generalized sliding indicator ([Sliding Indicator](references/patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.
|
|
1272
1272
|
|
|
1273
1273
|
```tsx
|
|
1274
1274
|
'use client';
|
|
@@ -44,7 +44,7 @@ Reserve directional slides for hierarchical navigation (list → detail) and ord
|
|
|
44
44
|
## Availability
|
|
45
45
|
|
|
46
46
|
- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
|
|
47
|
-
- **Without Next.js:**
|
|
47
|
+
- **Without Next.js:** Use stable `react` and `react-dom` 19.3 or newer (`ViewTransition` and `addTransitionType` became stable in React 19.3). Earlier stable React versions do not include these APIs.
|
|
48
48
|
- Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
|
|
49
49
|
|
|
50
50
|
---
|
|
@@ -10,14 +10,16 @@ listed in the generator's `VENDORED_SKILL_DIRS`.
|
|
|
10
10
|
- **Credit:** {{CREDIT:react-view-transitions:skills/react-view-transitions}}
|
|
11
11
|
|
|
12
12
|
The licence is MIT, declared in the upstream repo README's `## License`. Upstream ships no LICENSE
|
|
13
|
-
file (neither at the pinned commit nor on `main`; re-checked at
|
|
13
|
+
file (neither at the pinned commit nor on `main`; re-checked at 1a2c79d4), so there is no license text to carry here
|
|
14
14
|
and the entry's `licenseFile` is null; the README's declaration is the whole grant.
|
|
15
15
|
|
|
16
16
|
The skill follows the [Agent Skills](https://agentskills.io/) format (`SKILL.md` +
|
|
17
17
|
`references/`). Its internal links point at the upstream project's own files; do not
|
|
18
|
-
"fix" them to Geneseed paths — that is why the folder is gate-exempt.
|
|
18
|
+
"fix" them to Geneseed paths — that is why the folder is gate-exempt. Deviation 4 below only
|
|
19
|
+
repoints links that miss a sibling file of this folder. To update,
|
|
19
20
|
re-copy the upstream folder (new or removed files included, e.g. `references/troubleshooting.md`), re-apply the deviations below, and bump the entry's `commit`
|
|
20
|
-
in `src/upstreams.json`.
|
|
21
|
+
in `src/upstreams.json`. Afterwards every relative link in every `.md` here must resolve to a
|
|
22
|
+
file inside this folder.
|
|
21
23
|
|
|
22
24
|
**Deviation 1:** upstream's frontmatter says `name: vercel-react-view-transitions`;
|
|
23
25
|
here it is `name: react-view-transitions`. The Agent Skills format requires the name to
|
|
@@ -29,6 +31,13 @@ here it is `` `ViewTransition` ``. The Agent Skills spec forbids XML tags in a d
|
|
|
29
31
|
`checkBuild`'s description arm reports one for every first-party skill — the tag would be the
|
|
30
32
|
only one left in any install's catalogue.
|
|
31
33
|
|
|
34
|
+
**Deviation 4:** upstream's `AGENTS.md` is compiled from `SKILL.md` and the `references/` files,
|
|
35
|
+
and keeps the references' sibling-relative links, which miss at the folder root. In `AGENTS.md`
|
|
36
|
+
only, `](<name>.md` becomes `](references/<name>.md` for `<name>` in `css-recipes`,
|
|
37
|
+
`implementation`, `nextjs`, `patterns` and `troubleshooting` (any `#anchor` kept), and
|
|
38
|
+
`](../SKILL.md` becomes `](SKILL.md`. Links already written `](references/…` are left alone.
|
|
39
|
+
The other files keep upstream's links byte for byte: they already resolve.
|
|
40
|
+
|
|
32
41
|
**Deliberately not copied:** upstream's `README.md` (the repo-facing readme: install
|
|
33
42
|
command and folder tree, nothing an agent reads). `AGENTS.md`, upstream's compiled
|
|
34
43
|
all-in-one copy, IS kept — `SKILL.md`'s closing section points the agent at it.
|
|
@@ -78,7 +78,7 @@ spring:
|
|
|
78
78
|
The `CircuitBreaker` filter needs a Spring Cloud CircuitBreaker starter (for example the reactor-Resilience4j one) on the classpath. Gateway is WebFlux; do not put it in the same module as a Spring MVC service.
|
|
79
79
|
|
|
80
80
|
## Observability
|
|
81
|
-
- Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest.
|
|
81
|
+
- Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those, and permit `/actuator/health/**` in the security chain. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest. `management.endpoint.health.show-components: always` with `show-details: when-authorized` tells an anonymous caller which component is down without leaking hosts or versions.
|
|
82
82
|
- Metrics: add `micrometer-registry-prometheus` and expose `prometheus`.
|
|
83
83
|
- Traces over OTLP: add `org.springframework.boot:spring-boot-starter-opentelemetry` and configure `management.opentelemetry.tracing.export.otlp.endpoint` (the old `management.otlp.tracing.*` keys are not the Boot 4 names). Boot samples 10% by default; set `management.tracing.sampling.probability: 1.0` only where the volume allows.
|
|
84
84
|
- Custom spans: `Observation.createNotStarted("order.process", registry).lowCardinalityKeyValue(...).observe(() -> ...)` (Micrometer Observation, unchanged by Boot 4 as far as the docs show).
|
|
@@ -99,5 +99,23 @@ Add a short Kubernetes `preStop` sleep so the endpoint leaves the load balancer
|
|
|
99
99
|
- GraalVM native: fast start and low memory, at the cost of build time and reflection hints; adopt it deliberately, not by default.
|
|
100
100
|
- Use whatever CI the project already has; do not introduce a new one.
|
|
101
101
|
|
|
102
|
+
## Local dependencies
|
|
103
|
+
Give each Docker Compose dependency a healthcheck, and make the services that need it wait with `depends_on: { <dep>: { condition: service_healthy } }`; `docker compose up -d --wait` then also returns only once everything is usable. Write a shell check as `["CMD-SHELL", "<script>"]`, never `["CMD", "bash", "-c", "<script>"]`: Podman splits that array on spaces and reports the service healthy before it starts.
|
|
104
|
+
|
|
102
105
|
## Kubernetes manifest essentials
|
|
103
106
|
Liveness and readiness probes on the actuator paths, a startup probe for slow starts, resource requests and limits, `runAsNonRoot`, config from ConfigMap and Secret. For TLS, let the platform terminate it (Ingress plus cert-manager) or mount the certificate and use an SSL bundle ([spring-boot/security.md](security.md)).
|
|
107
|
+
|
|
108
|
+
No committed manifest names a cluster, host, registry, namespace or secret value: no `namespace:` (it comes from `-n`), the image is a bare name (Skaffold `--default-repo`), Secrets are referenced by name and created out of band.
|
|
109
|
+
|
|
110
|
+
Dependencies deployed in the same namespace get the same three probes, or a redeploy routes traffic to a pod that is not ready:
|
|
111
|
+
- PostgreSQL: `pg_isready -h 127.0.0.1` (over TCP: during the first `initdb` the server listens only on its socket), a fast startup probe; data on a PVC with `strategy: Recreate`, or every redeploy starts empty.
|
|
112
|
+
- Keycloak: `KC_HEALTH_ENABLED=true`, then `/health/started`, `/health/ready`, `/health/live` on management port 9000, not 8080.
|
|
113
|
+
|
|
114
|
+
Prove a new probe can fail: watch the service start and see Warning events before it is up (`kubectl get events --field-selector type=Warning`), with no restarts in the pods that depend on it.
|
|
115
|
+
|
|
116
|
+
## One set of manifests for several platforms
|
|
117
|
+
When one service deploys to a local cluster, plain Kubernetes and OpenShift, use Kustomize overlays (deployed with Skaffold or `kubectl -k`):
|
|
118
|
+
- `deploy/base` is plain Kubernetes, valid anywhere; `deploy/overlays/<platform>` adds only what that platform needs (Routes on OpenShift, Ingresses elsewhere); environment overlays with hosts and TLS stay out of git.
|
|
119
|
+
- Stay within the kustomize 3.8 features that Skaffold, `kubectl -k` and `oc -k` all support (`resources`, `patches`, generators); no `labels`, `replacements` or `components`.
|
|
120
|
+
- Selectors stay `app: <name>`: a selector cannot change after the first deploy.
|
|
121
|
+
- CI runs `kustomize build` on every overlay, so a broken patch fails the build, not the deploy.
|
|
@@ -41,8 +41,9 @@ log.error("Payment failed for order {}", order.id(), e); //
|
|
|
41
41
|
```
|
|
42
42
|
- Placeholders, never string concatenation. Guard only genuinely expensive arguments with `isDebugEnabled()`.
|
|
43
43
|
- Pass the exception as the final argument; do not log `e.getMessage()` alone.
|
|
44
|
-
- Log an exception once, where
|
|
45
|
-
-
|
|
44
|
+
- Log an exception once, where the flow ends (the exception handler, listener or job), not at every layer it passes through: a lower layer wraps it with context and rethrows, without logging. Expected business errors (404, validation) are `WARN` or `DEBUG` without a stack trace; only unexpected failures are `ERROR` with the throwable.
|
|
45
|
+
- For fields a log platform should filter on, use the SLF4J 2 fluent API: `log.atError().addKeyValue("orderId", id).setCause(e).log("Order processing failed")`. Boot's structured formats write each pair as a JSON field.
|
|
46
|
+
- Never log secrets, tokens, passwords, `Authorization` or `Cookie` headers, card data or personal data; log identifiers. A record prints every component in `toString()`: log its id, not the record, when it carries personal data. No full request or response bodies in production.
|
|
46
47
|
- Lombok's `@Slf4j` is fine where the project uses Lombok; otherwise declare the logger as above.
|
|
47
48
|
|
|
48
49
|
| Level | Meaning |
|
|
@@ -76,7 +77,7 @@ class MdcFilter extends OncePerRequestFilter {
|
|
|
76
77
|
}
|
|
77
78
|
```
|
|
78
79
|
|
|
79
|
-
MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run.
|
|
80
|
+
MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run. `CompletableFuture.supplyAsync(...)` without an executor runs on the common pool and loses MDC: always pass the Spring executor.
|
|
80
81
|
|
|
81
82
|
Useful fields for incident analysis: `requestId`, user or tenant id, and a duration on slow-path logs. Keep them to identifiers, not payloads.
|
|
82
83
|
|
|
@@ -86,4 +87,5 @@ Useful fields for incident analysis: `requestId`, user or tenant id, and a durat
|
|
|
86
87
|
| JSON console | `logging.structured.format.console: logstash` |
|
|
87
88
|
| Per-package level | `logging.level.com.example.orders: DEBUG` |
|
|
88
89
|
| Correlate a request | MDC `requestId` set in a filter |
|
|
90
|
+
| One event's fields as JSON | `log.atInfo().addKeyValue("k", v).log("msg")` |
|
|
89
91
|
| Follow one request in JSON logs | `jq 'select(.requestId == "abc")' app.log` (field name depends on MDC key and format) |
|