Docs UX: improve visual hierarchy, code marking, syntax highlighting, and authoring rules

[cssbruno]

Summary

The documentation site is readable but visually too flat. On /docs/language, language constructs, commands, paths, and identifiers do not stand apart strongly enough from prose, while the page opens with a dense capability paragraph that is difficult to scan.

There is also a concrete rendering defect: the first paragraph is extracted as the hero lead and then rendered again in the article body, so the introduction appears twice.

Current behavior and likely causes

• docs/language/README.md presents the implementation status as one roughly 200-word paragraph. It mixes supported, partial, and unsupported capabilities without visual grouping.
• docs-site/cmd/syncdocs/main.go extracts the first paragraph with frontMatter, but stripFirstH1 removes only the H1. The lead therefore remains in the generated article.
• Inline code has only a very soft background in docs-site/app.css. Correctly backticked constructs can still blend into the page, and unmarked constructs look exactly like ordinary text.
• Goldmark emits fenced blocks as <pre><code class="language-*">, and the site styles the container, but there is no token-level syntax-highlighting stage or token palette.
• The repository has theme guidance, but no documentation authoring standard that defines when commands, syntax, identifiers, filenames, flags, literals, and output must be marked as code.

Goal

Make the docs feel like a precise developer reference rather than a plain Markdown dump, while keeping the existing calm Go-inspired visual direction. Readers should be able to distinguish prose, syntax, commands, identifiers, examples, status, warnings, and output at a glance.

Implementation plan

1. Fix duplicated page leads

• Update the sync pipeline so the paragraph promoted to .doc-lead is removed from the article body.
• Prefer an explicit page-summary/front-matter representation over positional parsing if the format is expanded later.
• Add tests covering an H1 followed by a lead, an H1 without a lead, lists immediately after the H1, and code blocks immediately after the H1.

2. Restructure the language landing page

Rewrite docs/language/README.md so the current implementation status is scannable:

• one short overview paragraph;
• grouped sections such as Implemented, Partial/experimental, and Not yet implemented;
• a compact capability table or grouped bullet list;
• links to the detailed specification pages;
• a minimal .gwdk example near the top.

Avoid repeating the full compiler feature inventory in prose.

3. Add semantic code presentation

• Add build-time syntax highlighting for at least gwdk, go, sh/console, json, toml, and yaml fences.
• Define a small GOWDK lexer/token mapping for directives, blocks, attributes, strings, comments, identifiers, and literals.
• Keep highlighting static at build time; do not require a client-side highlighting runtime.
• Add a visible language label to fenced blocks.
• Preserve the copy action, make it keyboard accessible, and ensure it remains discoverable on touch devices.
• Strengthen inline-code treatment with sufficient contrast plus a subtle border/background so meaning is not conveyed by font family or color alone.
• Ensure long commands scroll safely and inline code wraps without breaking the layout.

4. Improve visual hierarchy without a full redesign

• Refine heading spacing and section separation.
• Add restrained status callouts or summary panels where content has clear semantic groups.
• Use tables for capability/status matrices rather than long comma-separated paragraphs.
• Keep the reading measure and responsive layout comfortable on desktop, tablet, and mobile.
• Reuse the existing theme tokens and avoid decorative cards around every paragraph.

5. Add a documentation authoring standard

Create docs/engineering/documentation-style.md and link it from docs/engineering/conventions.md.

Codify these rules:

1. Wrap CLI commands, flags, environment variables, config keys, code identifiers, package names, filenames, paths, routes, HTTP methods, syntax literals, and GOWDK constructs in backticks when used inline.
2. Use fenced blocks for multiline code and always provide an explicit language tag.
3. Use sh for copyable shell commands without a prompt. Use console only for transcripts that intentionally include prompts or output.
4. Use gwdk for GOWDK source examples and the correct tag for every other language.
5. Do not use bold or italics as a substitute for code markup.
6. Start each page with one H1 and one concise lead; the rendered lead must appear only once.
7. Split parallel lists of four or more items into bullets, a table, or clearly labeled groups.
8. Treat prose paragraphs over roughly 120 words as a lint warning, with documented exceptions for normative specification text.
9. Do not skip heading levels. Use headings to describe reader tasks or concepts, not vague labels such as “More”.
10. Use canonical vocabulary consistently: command, directive, block, attribute, identifier, route, handler, and component must not be interchanged casually.
11. Do not rely on color alone for meaning. Code, warnings, status, focus, and selected states need a second visual cue.
12. Keep examples minimal, valid, and copyable; explain placeholders explicitly.

6. Add automated documentation checks

Add a lightweight docs lint/test step that checks:

• fenced code blocks without language tags;
• duplicate lead rendering;
• skipped heading levels;
• excessively long prose paragraphs as warnings;
• broken internal .md links/routes;
• representative generated HTML snapshots for inline code and highlighted fences.

Likely files

• docs/language/README.md
• docs-site/cmd/syncdocs/main.go
• docs-site/cmd/syncdocs/main_test.go (new)
• docs-site/app.css
• docs-site/src/components/docs-page.cmp.gwdk
• docs/engineering/documentation-style.md (new)
• docs/engineering/conventions.md
• .github/workflows/ci.yml

Acceptance criteria

• The /docs/language lead appears once.
• The opening capability overview is grouped and scannable, with no wall-of-text feature inventory.
• Inline commands and syntax are visibly distinct at normal zoom without relying on color alone.
• Fenced gwdk, go, shell, JSON, TOML, and YAML examples receive token-level highlighting.
• Code blocks expose a language label and an accessible copy action.
• The new documentation style guide is linked from engineering conventions.
• CI detects missing fence languages and regressions in lead/code rendering.
• Desktop and mobile views have no code overflow or clipped controls.
• Contrast and keyboard-focus states meet the project’s accessibility expectations.

Out of scope

This issue should not replace the navigation architecture, introduce a documentation framework, or perform a full brand redesign. The focus is content hierarchy, semantic code treatment, rendering correctness, and enforceable authoring rules.