netcracker/ai-for-dummies

Fork 0

Files

T

Marcos Paulo 79920c9e6c

verify-and-publish / gate (push) Successful in 7m4s

Details

verify-and-publish / publish (push) Has been skipped

Details

feat: give the chapters motion, diagrams, and retrieval practice

Three strands of work on the chapter surface, all reading from the same
constraint: this site ships no runtime dependencies, so every effect below
is native CSS or an .astro component.

Motion (src/styles/motion.css, DrawRule.astro). A scroll-driven layer of
reveals, hero parallax, section depth, and a hairline that paints itself
along its path, scrubbed by `animation-timeline: view()` — 0KB against
lottie-web's ~60KB gzipped on the main thread. Every scrubbed rule sits
inside `prefers-reduced-motion: no-preference` and `@supports`, so a
Firefox reader or an opted-out one gets the complete static page rather
than one with holes in it. Ranges key to `cover 40%`-`cover 75%` where the
motion is meant to be watched: `view()` ranges key to first visibility,
which on a 2600px page is long before anyone is reading the section.
`.agents/skills/motion/references/scroll-driven.md` records the technique
and the two ways `pathLength` normalisation was broken while building it.

Diagrams (StepFlow.astro, WorktreeMap.astro). The `.steps` stack on
/skills/, /models/, and /agents/ becomes a numbered flow with connectors,
and /agents/ grows the worktree map it was describing in prose — reusing
the `trees` collection rather than a second set of strings. The map's
static variant is gated one class deeper than full-guide's page styles, so
the interactive copy renders byte-identical. Connectors are pseudo-elements,
not SVG: a stretched path desynchronises its own dash pattern, and a
straight line does not need one. Mermaid was considered and rejected at
~1MB of runtime.

Retrieval practice (/rules/, /skills/). A "check yourself" section of
native `<details>` question/answer pairs plus a citation row, both bilingual
through the existing `data-copy` toggle, and both JavaScript-free.

Two audit blind spots surfaced and are closed rather than worked around:
`build.inlineStylesheets: 'never'`, because Astro inlined sheets under ~4kB
and audit-ui.mjs reads its colour and size baseline from dist/_astro/*.css;
and `--columns` declared in the grid components, because an element-level
custom property is not a declaration the audit can resolve.

legacy/styles/skills.css is renamed and imported for its side effect. Inside
a *page*, `?url` resolves to that page's own CSS chunk whatever file it
names, so the link pointed at the wrong asset and the sheet was emitted but
never loaded — the package preview had been rendering unstyled and
overflowing since the Astro cutover.

verify.mjs gains 5 assertions for the recall sections and their Portuguese
copy: 89 now, against the 84 baseline.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-09-06 16:04:08 -03:00

4.9 KiB

Raw Blame History

Context: architecture

Current (Astro, static output)

Ten routes, one src/pages/ entry each, built to dist/:

Route	Page	Islands
`/`	`src/pages/index.astro`	—
`/full-guide/`	`src/pages/full-guide.astro`	`GuideSelector`, `LanguageToggle`, `CopyPrompt`
`/summary/`	`src/pages/summary.astro`	—
`/models/`	`src/pages/models.astro`	—
`/agents/`	`src/pages/agents.astro`	—
`/skills/`	`src/pages/skills.astro`	`SkillPackageExplorer`
`/rules/`	`src/pages/rules.astro`	`RulesInteractive`
`/skills-review/`	`src/pages/skills-review.astro`	`legacy/skills-review/app.js`
`/hands-on/starter/`	`public/` lab fixture	own
`/hands-on/rules/`	`public/` lab fixture	own

What is still unmigrated

legacy/ holds the parts the migration did not componentize. They are not dead files — the pages listed above import them, and the build fails without them.

legacy/styles/guide.css (was styles.css) — the editorial visual system, imported by full-guide.astro.
legacy/styles/audit.css (was full-guide/audit.css) — responsive audit overrides, imported by full-guide.astro.
legacy/styles/chapters.css — imported by ChapterLayout.astro.
legacy/styles/skills-chapter.css, skills-review.css, change-lens.css — imported by their respective pages. skills-chapter.css is imported for its side effect, not through the ?url + <link slot="styles"> pattern the layout uses: inside a page, ?url on a stylesheet resolves to that page's own CSS chunk rather than to the imported file, so the link points at the wrong asset and the sheet is emitted but never loaded. It was named skills.css and silently unloaded that way until 2026-09-06.
legacy/skills-review/ — app.js and the module graph under it (catalog.js, submitted-catalog.js, files.js, submitted-files.js, vote.js). catalog.js + submitted-catalog.js are the review desk's real data model, 24 entries; they are a content collection in all but name.

These sit outside src/ deliberately: check-tokens.mjs sweeps src, and these files are full of raw hex and unnamed breakpoints. Moving one into src/ means migrating it to tokens in the same change, not adding an exclusion.

responsive.css, landing.css, app.js, rules/app.js, rules/styles.css, and skills/app.js were deleted at cutover: their content lives in components.

Layout

src/
  content/            catalog entries, chapter copy, EN/PT strings (typed collections)
  layouts/            BaseLayout, ChapterLayout, GuideLayout
  components/         .astro by default; islands only where marked
  styles/             tokens.css, base.css, then per-component styles
  pages/              routes mirroring today's URLs exactly
public/
  hands-on/           lab fixtures copied verbatim, never processed

Non-negotiables

URLs do not change. /full-guide/, /skills-review/, /hands-on/starter/ and the rest must resolve exactly as they do now, trailing slash included. Existing links (including docs/, SilverBullet, and shared URLs with ?author=…&skill=…&view=… query params) must keep working.
Zero JS by default. Seven of the ten pages ship no JavaScript. They must still ship none. Islands are opt-in, per component, and justified.
hands-on/ stays vanilla. It lives in public/ untouched. It is a lab fixture, not a component.
No external runtime requests. audit-ui.mjs enforces this and it is part of the site's thesis. Self-host anything you add.
The review desk's query-param deep links keep working — ?author=, ?skill=, ?view=, ?file=, ?compare=, ?render=. They are documented in the page footer and shared externally.

Companion service

The vote API is a Go service on its own Kubernetes deploy cycle, reached by the review desk over window.SKILLS_REVIEW_VOTE_API. Its source left this repository on 2026-09-06; the deployed service is unchanged, and the review desk still calls it. Keep the global, or replace it with a build-time PUBLIC_VOTE_API env var — but if you do, update the service's own README in the same change.

Its one-vote-per-IP assertion left verify.mjs with it. See assertion-removals.md.

4.9 KiB Raw Blame History