Cloonar/deckle
3
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions

Basic theme: forkable neutral theme styling all shipped elements (design review) #15

New issue
Closed
opened 2026-07-11 13:01:36 +02:00 by dominik.polakovics · 2 comments
dominik.polakovics commented 2026-07-11 13:01:36 +02:00
Owner
Copy link

What to build

The forkable starting-point theme (docs/DECISIONS.md D7, D24): clean neutral typography, header with tree-derived navigation (one dropdown level, honoring hidden/menuTitle/weight), footer from tree-flagged pages, mobile-first styles for every element in the system library, no JS framework. Implements the theme contract: {{ partial "ce/attrs" . }} on every block element's root tag (emits data-ce-* markers only under hugo.IsServer), page-type declarations, no config beyond documented params.

This slice is HITL: the visual result needs human design review before it becomes the default scaffold.

Acceptance criteria

  • Sample site renders fully styled with every system element demonstrated on example pages
  • Navigation derives from the page tree with weight ordering, hidden flags, and menuTitle overrides; one dropdown level works on touch and desktop
  • All element templates carry ce/attrs; production build output contains no data-ce-* attributes
  • Lighthouse on the sample site: no accessibility failures from theme markup; responsive from 320 px up
  • Theme is self-contained under themes/ and documented as "fork me" with a short customization guide
  • Human design review of the rendered sample site is approved

Blocked by

## What to build The forkable starting-point theme (docs/DECISIONS.md D7, D24): clean neutral typography, header with tree-derived navigation (one dropdown level, honoring `hidden`/`menuTitle`/`weight`), footer from tree-flagged pages, mobile-first styles for every element in the system library, no JS framework. Implements the theme contract: `{{ partial "ce/attrs" . }}` on every block element's root tag (emits data-ce-* markers only under `hugo.IsServer`), page-type declarations, no config beyond documented params. This slice is HITL: the visual result needs human design review before it becomes the default scaffold. ## Acceptance criteria - [ ] Sample site renders fully styled with every system element demonstrated on example pages - [ ] Navigation derives from the page tree with weight ordering, hidden flags, and menuTitle overrides; one dropdown level works on touch and desktop - [ ] All element templates carry `ce/attrs`; production build output contains no data-ce-* attributes - [ ] Lighthouse on the sample site: no accessibility failures from theme markup; responsive from 320 px up - [ ] Theme is self-contained under `themes/` and documented as "fork me" with a short customization guide - [ ] Human design review of the rendered sample site is approved ## Blocked by - #14
dominik.polakovics commented 2026-07-12 02:17:11 +02:00
Author
Owner
Copy link

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Build the forkable, neutral starting-point theme under themes/: mobile-first styling for every element in the system library, a header with tree-derived navigation (one dropdown level honoring weight/hidden/menuTitle), a footer built from tree-flagged pages, no JS framework, and the ce/attrs theme contract on every block element's root tag.

Dependency note: this issue is hard-blocked by #14 (system element library). The theme styles the semantic, class-only markup that #14's shortcode templates emit — every element this theme must style, and the sample pages demonstrating them, come from that issue. The scheduler handles ordering. The issue body's docs/DECISIONS.md D7, D24 references point at a file that is not committed — this brief is self-contained.

Note on ready-for-human: this issue is deliberately labeled ready-for-human, not ready-for-agent. The implementation could well be agent-drafted, but acceptance hinges on subjective visual design judgment — the rendered result becomes the default scaffold every new site starts from (#17) — and it ends with an explicit human design-review approval, which an AFK agent cannot self-certify. An agent may be used as a drafting tool under human direction; the final call is human.

Current behavior:
The sample site has only minimal hand-written layouts, enough to prove the harness, preview, and round-trip engine work; there is no theme and no themes/ directory. Once #14 lands, every v1 element exists as a shortcode template emitting semantic, theme-agnostic markup (classes only, no inline styles) with a matching sidecar — but nothing styles that markup, navigation is not derived from the page tree, and no mechanism marks rendered elements for the editor.

Desired behavior:

A forkable theme. A self-contained Hugo theme lives under themes/, intended to be copied into new sites by harness init (#17) and owned by the site developer from then on. Clean, neutral typography and spacing — a credible default, not a showcase. No JS framework; prefer CSS-only solutions, with small vanilla JS allowed only where strictly necessary (e.g. the mobile nav toggle). The theme ships a short "fork me" customization guide: where colors/typography/spacing live, how to restyle an element, how to extend a layout. It requires no site configuration beyond its documented params.

Every element styled, mobile-first. All elements from #14's library render well-styled: grid (its full responsive column-width set), spacer, text, text-media, image, gallery, hero, quote, video-embed (including its pre-consent click-to-load facade), accordion, page-teasers, html, button, icon. Styles are written mobile-first and hold from 320px viewport width up with no horizontal overflow.

Header navigation from the page tree. The header nav derives from the content tree itself, not from a configured Hugo menu: entries ordered by weight, pages flagged hidden excluded, menuTitle overriding the page title when present. Exactly one dropdown level — a section with children gets a dropdown listing them. The dropdown works on both touch and pointer devices and is keyboard-accessible (focus states, correct ARIA semantics).

Footer from tree-flagged pages. Pages carrying a documented front-matter flag appear in the footer navigation — the typical use is imprint/privacy pages that are hidden from the header but must remain reachable.

Theme contract for the editor. Every block element template's root tag carries {{ partial "ce/attrs" . }}. The partial lives in the theme and emits data-ce-* attributes identifying the rendered element instance — enough for the click-to-select bridge (#16) to map a rendered DOM node back to the element in the page's parsed tree — and it emits them only when hugo.IsServer is true. A production build (hugo without server) contains zero data-ce-* attributes. The theme also provides the layouts for the shipped page types (home, standard page, section list) so a scaffolded site works out of the box.

Accessibility. A Lighthouse run against the sample site reports no accessibility failures attributable to theme markup: landmarks, heading order, contrast, focus visibility, nav semantics.

Sample site. The sample site uses the theme, and #14's example pages — one rendered example of every element — display fully styled, so the design review has something concrete to approve.

Key interfaces:

  • The ce/attrs partial is a contract consumed by #16 — document what the emitted data-ce-* markers mean (page identity plus element address within the page) and keep emission strictly behind hugo.IsServer.
  • Front-matter contract honored by the theme: weight (nav ordering), hidden (exclude from header nav), menuTitle (nav label override), and a documented footer flag.
  • The element class names emitted by #14's templates are the styling interface; the theme styles them without requiring markup changes. If styling exposes a genuine markup deficiency, fix it in the element template as a small semantic change — never with inline styles.
  • Theme params (if any) are documented in the theme's README; there is no undocumented configuration.

Acceptance criteria:

  • A self-contained theme under themes/ styles the sample site; every system element from #14 is demonstrated fully styled on example pages
  • Header nav derives from the page tree with weight ordering, hidden exclusion, and menuTitle overrides; one dropdown level works on touch and desktop and is keyboard-accessible
  • Footer navigation lists exactly the tree-flagged pages
  • Every block element template's root tag calls the ce/attrs partial; a hugo server build carries data-ce-* markers and a production hugo build contains none (verified by a test)
  • No JS framework is shipped; styles are mobile-first and the site is responsive from 320px up with no horizontal overflow
  • Lighthouse on the sample site reports no accessibility failures caused by theme markup
  • The theme is documented as "fork me" with a short customization guide
  • Human design review of the rendered sample site is approved — this criterion cannot be self-certified by an agent

Out of scope:

  • The element templates and sidecars themselves (#14) — beyond minimal semantic-markup fixes needed for honest styling
  • The click-to-select bridge and viewport toggle (#16) — the theme only emits the markers
  • Copying the theme into new sites (#17 harness init)
  • Page tree UI in the SPA (#4) and page management (#9)
  • Multiple themes, theme switching, or a theme-configuration UI
  • Dark mode or additional color schemes
> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Build the forkable, neutral starting-point theme under `themes/`: mobile-first styling for every element in the system library, a header with tree-derived navigation (one dropdown level honoring `weight`/`hidden`/`menuTitle`), a footer built from tree-flagged pages, no JS framework, and the `ce/attrs` theme contract on every block element's root tag. **Dependency note:** this issue is **hard-blocked by #14** (system element library). The theme styles the semantic, class-only markup that #14's shortcode templates emit — every element this theme must style, and the sample pages demonstrating them, come from that issue. The scheduler handles ordering. The issue body's `docs/DECISIONS.md D7, D24` references point at a file that is not committed — this brief is self-contained. **Note on `ready-for-human`:** this issue is deliberately labeled `ready-for-human`, not `ready-for-agent`. The implementation could well be agent-drafted, but acceptance hinges on subjective visual design judgment — the rendered result becomes the default scaffold every new site starts from (#17) — and it ends with an explicit human design-review approval, which an AFK agent cannot self-certify. An agent may be used as a drafting tool under human direction; the final call is human. **Current behavior:** The sample site has only minimal hand-written layouts, enough to prove the harness, preview, and round-trip engine work; there is no theme and no `themes/` directory. Once #14 lands, every v1 element exists as a shortcode template emitting semantic, theme-agnostic markup (classes only, no inline styles) with a matching sidecar — but nothing styles that markup, navigation is not derived from the page tree, and no mechanism marks rendered elements for the editor. **Desired behavior:** *A forkable theme.* A self-contained Hugo theme lives under `themes/`, intended to be copied into new sites by `harness init` (#17) and owned by the site developer from then on. Clean, neutral typography and spacing — a credible default, not a showcase. No JS framework; prefer CSS-only solutions, with small vanilla JS allowed only where strictly necessary (e.g. the mobile nav toggle). The theme ships a short "fork me" customization guide: where colors/typography/spacing live, how to restyle an element, how to extend a layout. It requires no site configuration beyond its documented params. *Every element styled, mobile-first.* All elements from #14's library render well-styled: grid (its full responsive column-width set), spacer, text, text-media, image, gallery, hero, quote, video-embed (including its pre-consent click-to-load facade), accordion, page-teasers, html, button, icon. Styles are written mobile-first and hold from 320px viewport width up with no horizontal overflow. *Header navigation from the page tree.* The header nav derives from the content tree itself, not from a configured Hugo menu: entries ordered by `weight`, pages flagged `hidden` excluded, `menuTitle` overriding the page title when present. Exactly one dropdown level — a section with children gets a dropdown listing them. The dropdown works on both touch and pointer devices and is keyboard-accessible (focus states, correct ARIA semantics). *Footer from tree-flagged pages.* Pages carrying a documented front-matter flag appear in the footer navigation — the typical use is imprint/privacy pages that are `hidden` from the header but must remain reachable. *Theme contract for the editor.* Every block element template's root tag carries `{{ partial "ce/attrs" . }}`. The partial lives in the theme and emits `data-ce-*` attributes identifying the rendered element instance — enough for the click-to-select bridge (#16) to map a rendered DOM node back to the element in the page's parsed tree — and it emits them **only** when `hugo.IsServer` is true. A production build (`hugo` without server) contains zero `data-ce-*` attributes. The theme also provides the layouts for the shipped page types (home, standard page, section list) so a scaffolded site works out of the box. *Accessibility.* A Lighthouse run against the sample site reports no accessibility failures attributable to theme markup: landmarks, heading order, contrast, focus visibility, nav semantics. *Sample site.* The sample site uses the theme, and #14's example pages — one rendered example of every element — display fully styled, so the design review has something concrete to approve. **Key interfaces:** - The `ce/attrs` partial is a contract consumed by #16 — document what the emitted `data-ce-*` markers mean (page identity plus element address within the page) and keep emission strictly behind `hugo.IsServer`. - Front-matter contract honored by the theme: `weight` (nav ordering), `hidden` (exclude from header nav), `menuTitle` (nav label override), and a documented footer flag. - The element class names emitted by #14's templates are the styling interface; the theme styles them without requiring markup changes. If styling exposes a genuine markup deficiency, fix it in the element template as a small semantic change — never with inline styles. - Theme params (if any) are documented in the theme's README; there is no undocumented configuration. **Acceptance criteria:** - [ ] A self-contained theme under `themes/` styles the sample site; every system element from #14 is demonstrated fully styled on example pages - [ ] Header nav derives from the page tree with `weight` ordering, `hidden` exclusion, and `menuTitle` overrides; one dropdown level works on touch and desktop and is keyboard-accessible - [ ] Footer navigation lists exactly the tree-flagged pages - [ ] Every block element template's root tag calls the `ce/attrs` partial; a `hugo server` build carries `data-ce-*` markers and a production `hugo` build contains none (verified by a test) - [ ] No JS framework is shipped; styles are mobile-first and the site is responsive from 320px up with no horizontal overflow - [ ] Lighthouse on the sample site reports no accessibility failures caused by theme markup - [ ] The theme is documented as "fork me" with a short customization guide - [ ] Human design review of the rendered sample site is approved — this criterion cannot be self-certified by an agent **Out of scope:** - The element templates and sidecars themselves (#14) — beyond minimal semantic-markup fixes needed for honest styling - The click-to-select bridge and viewport toggle (#16) — the theme only emits the markers - Copying the theme into new sites (#17 `harness init`) - Page tree UI in the SPA (#4) and page management (#9) - Multiple themes, theme switching, or a theme-configuration UI - Dark mode or additional color schemes
dominik.polakovics commented 2026-07-13 01:07:41 +02:00
Author
Owner
Copy link

Closing as superseded: the maintainer has decided on a clean-slate reset of the project (issue #29, PR #30). The v1 implementation this issue builds on is being removed and the plan will be re-drawn from scratch; this spec is retired rather than actioned.

Closing as superseded: the maintainer has decided on a clean-slate reset of the project (issue #29, PR #30). The v1 implementation this issue builds on is being removed and the plan will be re-drawn from scratch; this spec is retired rather than actioned.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
afk/130
afk/129
afk/128
afk/124
afk/117
afk/116
afk/115
afk/114
afk/113
afk/112
afk/111
lab/20260718-0231
afk/95
afk/93
afk/91
afk/97
afk/90
afk/94
afk/96
afk/92
afk/89
lab/20260716-2349
afk/83
afk/72
afk/70
afk/58
afk/56
afk/54
afk/52
afk/50
afk/48
lab/20260715-1223
afk/44
afk/42
afk/40
afk/37
afk/35
afk/33
lab/20260712-0208
afk/9
afk/4
afk/14
afk/12
afk/10
afk/7
afk/6
afk/3
afk/2
afk/1
No results found.
Labels
Clear labels   
enhancement
New feature or improvement

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Fully specified, ready for an AFK agent

  
ready-for-human
Requires human implementation

No labels
enhancement
needs-triage
ready-for-agent
ready-for-human
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Cloonar/deckle#15
No description provided.