docs: redesign documentation site UI#15214
Conversation
![accesslint[bot]](https://avatars.githubusercontent.com/in/1502?s=60&v=4){kind=small}
| maintained by DefectDojo Inc. and the Open-Source community. | ||
| </p> | ||
| {{ with .Params.lead }}<p class="lead">{{ . }}</p>{{ end }} | ||
| <button type="button" id="ddHomeSearch" class="dd-hero-search" aria-label="Search documentation"> |
There was a problem hiding this comment.
Best Practice: Accessible name "Search documentation" does not contain visible text "Search the docs".
Interactive elements with visible text must have accessible names that contain that text.
Details
For voice control users who activate controls by speaking their visible label, the accessible name must include the visible text. If aria-label is 'Submit form' but the button shows 'Send', voice users saying 'click Send' won't activate it. Ensure aria-label/aria-labelledby contains or matches the visible text.
Presentation-only redesign of docs.defectdojo.com. The rendered text of all 612 pages is byte-identical to the previous build (verified by diffing extracted page text across before/after builds); no content files are touched. Highlights: - Token-based design system (CSS custom properties for light and dark) using the DefectDojo brand palette, with navy header and footer shared with trust.defectdojo.com - Code blocks restyled as navy cards in both color modes by retheming the doks expressive-code frame variables: language labels in the header band, terminal dots for shell fences, styled copy button, and a brand-tuned Chroma syntax palette - The Open Source / Pro version toggle is rebuilt from a select dropdown into an accessible segmented control (radiogroup semantics). Behavior is unchanged: same localStorage key and values, anti-flash reveal, edition-aware "Model Your Assets" nav link, and instances stay in sync across the desktop sidebar and mobile offcanvas - Reading experience: 16px root font size (was 85 percent), 72ch measure, refined heading scale, framed screenshots, styled tables and callouts - Mobile fixes: the header now shows the brand on small screens, and the offcanvas navigation actually opens. The site disables the full Bootstrap bundle (doks.bootstrapJavascript = false), so the offcanvas plugin never loaded and mobile nav buttons were dead on the live site; custom.js now imports just the Offcanvas plugin - Homepage: navy hero with blueprint grid, prominent DocSearch trigger, quick-nav cards overlapping the hero edge; all copy unchanged Note: netlify.toml pins HUGO_VERSION=0.125.1, which cannot build doks-core 1.8.3 (it requires Hugo 0.146+ for layouts/_partials). The production pipeline evidently uses a newer Hugo already; this change was built and verified with Hugo 0.148.1 extended. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The main nav row lives inside #offcanvasNavMain but outside .offcanvas-body in this header, so the white active-link rule never matched and the theme's Fuji Blue applied, which is hard to read on the navy band. Scope the desktop rules to .navbar-nav directly (active link is now white on a blue tint) and correct the mobile offcanvas scope the same way (link blue on the light panel). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Maffooch
force-pushed
the
devgrega/docs-redesign
branch
from
5d61d57 to
8e0c27e
Compare
The dark logo SVG is an auto-trace that carries its background as nine opaque fill paths (#212529), invisible on the old dark-gray header but visible as a box on the navy redesign. Delete the background paths and recolor the seven letter counters and pixel notches to the navy surface color so the wordmark renders clean in the header and footer. Same fix as applied to the trust-center copy of this logo; the SVG is still not truly transparent inside the letter counters, so reusing it on non-navy backgrounds would need a proper even-odd hole merge. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
| const storedVersion = localStorage.getItem("version") || "opensource"; | ||
| console.log("[VersionToggle] Stored version:", storedVersion); | ||
| setVersion(storedVersion); | ||
| // custom-head.html already stamped the stored edition on <html> before |
There was a problem hiding this comment.
WCAG 2.4.2: Document is missing a <title> element.
Documents must have a <title> element to provide users with an overview of content.
Details
Page text: "// custom js // Mobile navigation: the site sets doks.bootstrapJavascript = false, so no // Bootstrap plugins load and the header's offcanvas toggles "
Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').
Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.
Page must have a mechanism to bypass repeated blocks of content.
Details
Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings
Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.
Best Practice: Page does not contain a level-one heading.
Page should contain a level-one heading.
Details
A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.
Best Practice: Page has no main landmark.
Page should have exactly one main landmark.
Details
The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.
WCAG 3.1.1: <html> element missing lang attribute.
The <html> element must have a lang attribute.
Details
Page text sample: "// custom js // Mobile navigation: the site sets doks.bootstrapJavascript = false, so no // Bootstrap plugins load and the header's offcanvas toggles are dead markup. // Importing the Offcanvas plugin"
Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).
| --bs-btn-active-border-color: #cccccc; | ||
| --bs-btn-active-color: #191919; | ||
| } | ||
| // Selected state keys off the edition stamped on <html> before first |
There was a problem hiding this comment.
WCAG 2.4.2: Document is missing a <title> element.
Documents must have a <title> element to provide users with an overview of content.
Details
Page text: "// ============================================================ // DefectDojo Docs design system // // Imported last in doks-core app.scss — everythin"
Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').
Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.
Page must have a mechanism to bypass repeated blocks of content.
Details
Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings
Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.
Best Practice: Page does not contain a level-one heading.
Page should contain a level-one heading.
Details
A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.
Best Practice: Page has no main landmark.
Page should have exactly one main landmark.
Details
The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.
WCAG 3.1.1: <html> element missing lang attribute.
The <html> element must have a lang attribute.
Details
Page text sample: "// ============================================================ // DefectDojo Docs design system // // Imported last in doks-core app.scss — everything here wins the // cascade. Selectors defined here"
Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).
| <meta name="docsearch:audience" content="{{ .Params.audience | default " public" }}"> No newline at end of file | ||
| <meta name="docsearch:audience" content="{{ .Params.audience | default " public" }}"> | ||
| <script> | ||
| // Stamp the stored docs edition (Open Source / Pro) on <html> before first |
There was a problem hiding this comment.
WCAG 2.4.2: Document is missing a <title> element.
Documents must have a <title> element to provide users with an overview of content.
Details
Page text: "{{ if site.Params.add_ons.docSearch -}} {{ $options := (dict "targetPath" "/css/main.min.css" "outputStyle" "compressed") }} {{ $style := resources.Ge"
Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').
Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.
Page must have a mechanism to bypass repeated blocks of content.
Details
Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings
Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.
Best Practice: Page does not contain a level-one heading.
Page should contain a level-one heading.
Details
A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.
Best Practice: Page has no main landmark.
Page should have exactly one main landmark.
Details
The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.
WCAG 3.1.1: <html> element missing lang attribute.
The <html> element must have a lang attribute.
Details
Page text sample: "{{ if site.Params.add_ons.docSearch -}} {{ $options := (dict "targetPath" "/css/main.min.css" "outputStyle" "compressed") }} {{ $style := resources.Get "scss/app.scss" | css.Sass $options }} {{ end -}"
Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).
AccessLint flagged the label-in-name mismatch: aria-label said "Search documentation" while the visible text says "Search the docs", breaking voice-control activation. Drop the aria-label so the visible label is the accessible name. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
| const storedVersion = localStorage.getItem("version") || "opensource"; | ||
| console.log("[VersionToggle] Stored version:", storedVersion); | ||
| setVersion(storedVersion); | ||
| // custom-head.html already stamped the stored edition on <html> before |
There was a problem hiding this comment.
WCAG 2.4.2: Document is missing a <title> element.
Documents must have a <title> element to provide users with an overview of content.
Details
Page text: "// custom js // Mobile navigation: the site sets doks.bootstrapJavascript = false, so no // Bootstrap plugins load and the header's offcanvas toggles "
Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').
Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.
Page must have a mechanism to bypass repeated blocks of content.
Details
Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings
Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.
Best Practice: Page does not contain a level-one heading.
Page should contain a level-one heading.
Details
A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.
Best Practice: Page has no main landmark.
Page should have exactly one main landmark.
Details
The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.
WCAG 3.1.1: <html> element missing lang attribute.
The <html> element must have a lang attribute.
Details
Page text sample: "// custom js // Mobile navigation: the site sets doks.bootstrapJavascript = false, so no // Bootstrap plugins load and the header's offcanvas toggles are dead markup. // Importing the Offcanvas plugin"
Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).
| --bs-btn-active-border-color: #cccccc; | ||
| --bs-btn-active-color: #191919; | ||
| } | ||
| // Selected state keys off the edition stamped on <html> before first |
There was a problem hiding this comment.
WCAG 2.4.2: Document is missing a <title> element.
Documents must have a <title> element to provide users with an overview of content.
Details
Page text: "// ============================================================ // DefectDojo Docs design system // // Imported last in doks-core app.scss — everythin"
Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').
Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.
Page must have a mechanism to bypass repeated blocks of content.
Details
Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings
Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.
Best Practice: Page does not contain a level-one heading.
Page should contain a level-one heading.
Details
A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.
Best Practice: Page has no main landmark.
Page should have exactly one main landmark.
Details
The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.
WCAG 3.1.1: <html> element missing lang attribute.
The <html> element must have a lang attribute.
Details
Page text sample: "// ============================================================ // DefectDojo Docs design system // // Imported last in doks-core app.scss — everything here wins the // cascade. Selectors defined here"
Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).
| <meta name="docsearch:audience" content="{{ .Params.audience | default " public" }}"> No newline at end of file | ||
| <meta name="docsearch:audience" content="{{ .Params.audience | default " public" }}"> | ||
| <script> | ||
| // Stamp the stored docs edition (Open Source / Pro) on <html> before first |
There was a problem hiding this comment.
WCAG 2.4.2: Document is missing a <title> element.
Documents must have a <title> element to provide users with an overview of content.
Details
Page text: "{{ if site.Params.add_ons.docSearch -}} {{ $options := (dict "targetPath" "/css/main.min.css" "outputStyle" "compressed") }} {{ $style := resources.Ge"
Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').
Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.
Page must have a mechanism to bypass repeated blocks of content.
Details
Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings
Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.
Best Practice: Page does not contain a level-one heading.
Page should contain a level-one heading.
Details
A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.
Best Practice: Page has no main landmark.
Page should have exactly one main landmark.
Details
The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.
WCAG 3.1.1: <html> element missing lang attribute.
The <html> element must have a lang attribute.
Details
Page text sample: "{{ if site.Params.add_ons.docSearch -}} {{ $options := (dict "targetPath" "/css/main.min.css" "outputStyle" "compressed") }} {{ $style := resources.Get "scss/app.scss" | css.Sass $options }} {{ end -}"
Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).
The theme bleeds .docs-links 24px past its column (margin-right: -24px), which pushed every sidebar item outside the version-menu scroll wrapper; combined with the wrapper's overflow-x clipping, long labels, Pro badges, and the active pill were cut off at the right edge. Zero the bleed inside the wrapper and add slight right padding. Also: clicked summaries keep :focus-visible in most browsers, and the clipped outline ring rendered as stray horizontal lines around collapsed groups in dark mode. Replace the ring with a filled focus state, and ease group-label letter-spacing so long edition names wrap cleanly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
| --bs-btn-active-color: #fff; | ||
| font-weight: 500; // Medium for buttons | ||
| } | ||
| // Selected state keys off the edition stamped on <html> before first |
There was a problem hiding this comment.
WCAG 2.4.2: Document is missing a <title> element.
Documents must have a <title> element to provide users with an overview of content.
Details
Page text: "// ============================================================ // DefectDojo Docs design system // // Imported last in doks-core app.scss — everythin"
Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').
Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.
Page must have a mechanism to bypass repeated blocks of content.
Details
Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings
Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.
Best Practice: Page does not contain a level-one heading.
Page should contain a level-one heading.
Details
A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.
Best Practice: Page has no main landmark.
Page should have exactly one main landmark.
Details
The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.
WCAG 3.1.1: <html> element missing lang attribute.
The <html> element must have a lang attribute.
Details
Page text sample: "// ============================================================ // DefectDojo Docs design system // // Imported last in doks-core app.scss — everything here wins the // cascade. Selectors defined here"
Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).
Bootstrap breadcrumbs prefix each crumb with its "/" separator, so when the trail wrapped the separator dangled at the start of the next line. Keep the trail on one line and ellipsize long crumbs instead: "Home" never shrinks, ancestors compress to readable stubs, and the current page keeps roughly twice the room. The active item renders as a block because text-overflow does not draw an ellipsis on a flex container. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
| --bs-btn-active-color: #fff; | ||
| font-weight: 500; // Medium for buttons | ||
| } | ||
| // Selected state keys off the edition stamped on <html> before first |
There was a problem hiding this comment.
WCAG 2.4.2: Document is missing a <title> element.
Documents must have a <title> element to provide users with an overview of content.
Details
Page text: "// ============================================================ // DefectDojo Docs design system // // Imported last in doks-core app.scss — everythin"
Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').
Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.
Page must have a mechanism to bypass repeated blocks of content.
Details
Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings
Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.
Best Practice: Page does not contain a level-one heading.
Page should contain a level-one heading.
Details
A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.
Best Practice: Page has no main landmark.
Page should have exactly one main landmark.
Details
The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.
WCAG 3.1.1: <html> element missing lang attribute.
The <html> element must have a lang attribute.
Details
Page text sample: "// ============================================================ // DefectDojo Docs design system // // Imported last in doks-core app.scss — everything here wins the // cascade. Selectors defined here"
Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).
2 participants
Summary
Presentation-only redesign of docs.defectdojo.com, bringing the documentation up to the standard of the best developer docs (Stripe, Tailwind, Supabase) while keeping every word of content identical. The rendered text of all 612 pages is byte-identical to the previous build, verified by diffing extracted page text across before/after builds. No files under
docs/content/are touched.Design system
html { font-size: 85% }hack), 72ch reading measure, refined heading hierarchy, framed screenshots, styled tables and calloutsCode blocks
Open Source / Pro toggle
<select>dropdown into a segmented control with radiogroup semanticslocalStoragekey and values, anti-flash sidebar reveal, edition-aware "Model Your Assets" nav link, Pro badges, and all control instances (desktop sidebar plus mobile offcanvas) stay in syncMobile fixes (bugs live on production today)
doks.bootstrapJavascript = false, so the Offcanvas plugin never loaded and the header nav buttons did nothing.custom.jsnow imports just the Offcanvas plugin (verified: both offcanvas panels open, and the version toggle works from inside them)Homepage
Verification
Notes for maintainers
docs/netlify.tomlpinsHUGO_VERSION = "0.125.1", which cannot build doks-core 1.8.3 (layouts/_partialsrequires Hugo 0.146+). The production pipeline evidently already uses a newer Hugo; the pin looks stale but is deliberately not touched here.🤖 Generated with Claude Code