doc: Align docs theme with TTI brand guidelines and drop TTUI by calebthings · Pull Request #1500 · TheThingsIndustries/lorawan-stack-docs

calebthings · 2026-10-23T12:33:55Z

Summary

References #1499 (part 1 of 3). Aligns the docs theme with the current TTI brand guidelines and removes the dependency on The Things UI (TTUI 1.10.1), so design#323 can delete TTUI without breaking the docs.

Follow-up PRs, stacked on this one: accessibility fixes (doc/accessibility) and native Pagefind search replacing Algolia (doc/native-search). They will be opened after this one is merged.

Screenshots

Changes

Add common/tokens.scss (tts, grey and status scales, spacing, radius, motion) from the Figma brand variables; Bulma variables and legacy theme colors map onto it
Remove the TTUI stylesheet, scripts and the @ttui/design dependency; rebuild the home page and What's new partial without TTUI classes
Typefaces: Poppins SemiBold (headings), Inter variable (body), Geist Mono (code); remove ITC Avant Garde and unused Inter files
Non-clickable headings tts-1000; links and clickable card titles tts-500 (hover tts-700); 8px radii; Note/Warning callouts in status colors with Tabler icons
New The Things Stack logo, favicon and touch icon (SVG with a 64px PNG fallback and a 180px touch icon)
Home page section cards share one style with 40px Tabler outline icons (new icon.html partial)
Syntax highlighting colors pass WCAG AA on the code background
Navigation: labels "Cloud" and "Enterprise"; all sections as links from 1216px, grouped Deployment/Build dropdowns (params.navgroups) from 1024–1215px, menu button below; nothing clips at any width
Edition labels (Cloud, Enterprise, Sandbox, Open Source) at full size on their own line
Copy button on code blocks and on standalone code snippets (paragraphs, table cells, list items), shown on hover, keyboard focus and always on touch screens, with a screen reader announcement

Notes for Reviewers

No content changes; theme, config and static assets only.
Colors and type follow the brand folder (colors.md, typography.md) and the Figma variables.
Easiest to review by running make server and comparing the home page, a guide page and the navigation at 1440px, 1100px and 390px.

Checklist

Scope: The referenced issue is addressed, there are no unrelated changes.
Run Locally: Verified that the docs build using make server, posted screenshots, verified external links. Test with HUGO_PARAMS_SEARCH_ENABLED=true if style changes will affect the search bar.
New Features Marked: Documentation for new features is marked using the new-in-version shortcode, according to the guidelines in CONTRIBUTING.
Style Guidelines: Documentation obeys style guidelines in CONTRIBUTING.
Commits: Commit messages follow guidelines in CONTRIBUTING, there are no fixup commits left.

Copilot

🟡 Changes recommended

Code whitespace preservation, mobile snippet wrapping, and error-token contrast need correction before approval.

3 open issues

Limit code-cell nowrap to table cells · New
Restrict nowrap selector to direct table-cell code · New
Fix insufficient contrast for Chroma error tokens · New

What changed in this PR

Updates the Hugo documentation theme to current TTI branding and removes its dependency on retired TTUI assets. This implements the branding stage of #1499, ahead of the planned accessibility and native-search work.

Changes:

Introduces brand tokens, typography, icons, and shared styles; rebuilds home-page cards and callouts without TTUI.
Adds responsive navigation groups and copy buttons for code blocks and standalone snippets.
Replaces branding assets and includes generated Pagefind assets without switching the search integration.

File	Description
doc/yarn.lock	Removes the TTUI lockfile entry.
doc/themes/the-things-stack/layouts/shortcodes/warning.html	Updates warning markup and icon.
doc/themes/the-things-stack/layouts/shortcodes/note.html	Updates note markup and icon.
doc/themes/the-things-stack/layouts/shortcodes/cli-downloader.html	Replaces TTUI button classes.
doc/themes/the-things-stack/layouts/shortcodes/aws-deploy-cloudformation.html	Uses the replacement button style.
doc/themes/the-things-stack/layouts/partials/whats-new.html	Rebuilds featured-release cards.
doc/themes/the-things-stack/layouts/partials/pages-cards.html	Updates section-card styling.
doc/themes/the-things-stack/layouts/partials/icon.html	Adds reusable inline Tabler icons.
doc/themes/the-things-stack/layouts/partials/header/nav.html	Updates the logo and adds grouped navigation.
doc/themes/the-things-stack/layouts/partials/head/head.html	Updates favicon links and removes TTUI CSS.
doc/themes/the-things-stack/layouts/partials/footer/footer.html	Loads the copy-button script.
doc/themes/the-things-stack/layouts/index.html	Rebuilds the home page without TTUI.
doc/themes/the-things-stack/assets/js/theme.js	Removes TTUI imports and handles navigation groups.
doc/themes/the-things-stack/assets/js/copy-code.js	Adds clipboard controls and announcements.
doc/themes/the-things-stack/assets/icons/tabler/server-2.svg	Adds the Enterprise card icon.
doc/themes/the-things-stack/assets/icons/tabler/router.svg	Adds the Hardware card icon.
doc/themes/the-things-stack/assets/icons/tabler/rocket.svg	Adds the Getting Started card icon.
doc/themes/the-things-stack/assets/icons/tabler/plug-connected.svg	Adds the Integrations card icon.
doc/themes/the-things-stack/assets/icons/tabler/LICENSE	Includes the Tabler license.
doc/themes/the-things-stack/assets/icons/tabler/cloud.svg	Adds the Cloud card icon.
doc/themes/the-things-stack/assets/icons/tabler/bulb.svg	Adds the Concepts card icon.
doc/themes/the-things-stack/assets/icons/tabler/api.svg	Adds the API card icon.
doc/themes/the-things-stack/assets/css/theme.scss	Imports the new theme foundations.
doc/themes/the-things-stack/assets/css/pages/homepage.scss	Styles the rebuilt home page.
doc/themes/the-things-stack/assets/css/highlight.scss	Maps syntax colors to brand tokens.
doc/themes/the-things-stack/assets/css/header/nav.scss	Updates navigation borders and radius.
doc/themes/the-things-stack/assets/css/footer/footer.scss	Points to consolidated footer styles.
doc/themes/the-things-stack/assets/css/common/variables.scss	Maps Bulma settings to brand tokens.
doc/themes/the-things-stack/assets/css/common/typography.scss	Defines heading, body, and code styles.
doc/themes/the-things-stack/assets/css/common/tokens.scss	Defines shared design tokens.
doc/themes/the-things-stack/assets/css/common/tabs.scss	Refreshes tab styling.
doc/themes/the-things-stack/assets/css/common/global.scss	Updates shared styles and removes obsolete rules.
doc/themes/the-things-stack/assets/css/common/fonts.scss	Declares the replacement typefaces.
doc/themes/the-things-stack/assets/css/common/components.scss	Styles shared components and responsive navigation.
doc/themes/the-things-stack/assets/css/common/code.scss	Styles copy controls and snippet layouts.
doc/static/pagefind/pagefind.js	Adds the generated Pagefind runtime.
doc/static/pagefind/pagefind-worker.js	Adds the generated search worker.
doc/static/pagefind/pagefind-ui.css	Adds standard Pagefind UI styles.
doc/static/pagefind/pagefind-modular-ui.js	Adds modular Pagefind UI code.
doc/static/pagefind/pagefind-modular-ui.css	Adds modular Pagefind UI styles.
doc/static/pagefind/pagefind-entry.json	Adds generated search-index metadata.
doc/static/img/TTS-logo.svg	Removes the previous logo.
doc/static/img/tts-horizontal-standard-color.svg	Adds the current horizontal logo.
doc/static/favicon.svg	Replaces the favicon artwork.
doc/package.json	Removes the TTUI dependency.
doc/content/integrations/cloud-integrations/azure-iot-hub/deployment.md	Migrates the deployment button styling.
doc/content/enterprise/_index.md	Shortens the Enterprise navigation label.
doc/content/cloud/_index.md	Shortens and reorders the Cloud navigation entry.
doc/config/_default/config.toml	Configures Deployment and Build navigation groups.

_{Review effort: Balanced}

happyRip

It looks like an improvement on the previous website.

doc/static/pagefind/ fragments look like some local directory added by accident. It might be worth it adding that dir to .gitignore if they're generated on each local build.

happyRip · 2026-10-26T13:01:01Z

+          <a href="{{ $pagePermalink }}" class="whats-new-item">
+            <span class="pill pill--subtle">{{ $feature_category | title }}</span>
+            <span class="whats-new-item__text">{{ . | markdownify }}</span>
+            <span class="whats-new-item__arrow" aria-hidden="true">→</span>
+          </a>


There is an edge case where if a changelog entry would contain a link it would produce invalid HTML (nested <a> tag).
This was never the case so far, but if we can avoid it by using a <div> or something, then it might be worth it.

happyRip · 2026-10-26T13:03:58Z

+  <link rel="icon" type="image/png" sizes="64x64" href="{{ "favicon.png" | relURL }}">
+  <link rel="icon" type="image/png" sizes="120x120" href="{{ "favicon-120.png" | relURL }}">


This changed from alternate icon to icon. Is this intended?

Not intended, thanks for catching. Reverted.

happyRip · 2026-10-26T13:04:30Z

  <link rel="icon" type="image/svg+xml" href="{{ "favicon.svg" | relURL }}">
+  <link rel="icon" type="image/png" sizes="64x64" href="{{ "favicon.png" | relURL }}">
+  <link rel="icon" type="image/png" sizes="120x120" href="{{ "favicon-120.png" | relURL }}">
+  <link rel="apple-touch-icon" href="{{ "favicon-120.png" | relURL }}">


AFAIK the touch icon should be 180px.

It should indeed be 180px, adjusted now

Replace the retired The Things UI (TTUI 1.10.1) stylesheet and scripts with design tokens from the Figma brand variables, so the docs follow the current brand guidelines without an external dependency. - Add common/tokens.scss (tts, grey and status scales, spacing, radius, motion); Bulma variables and legacy theme colors map onto it - Remove the TTUI stylesheet, scripts and the @ttui/design dependency; rebuild the home page and What's new partial without TTUI classes - Typefaces: Poppins SemiBold (headings), Inter variable (body), Geist Mono (code); remove ITC Avant Garde and unused Inter files - Non-clickable headings tts-1000; links and clickable card titles tts-500 (hover tts-700); 8px radii; Note/Warning callouts in status colors with Tabler icons - New The Things Stack logo and favicon (SVG with a 64px PNG fallback and a 180px touch icon) - Home page section cards share one style and get 40px Tabler outline icons (new icon partial) - Syntax highlighting colors pass WCAG AA on the code background - Navigation: labels "Cloud" and "Enterprise"; every section as a link from 1216px, grouped Deployment and Build dropdowns (params.navgroups) from 1024px to 1215px, menu button below; search is a full field from 1344px and an icon below; 32px after the logo, 8px between items, Inter Medium 15/21. Nothing is clipped at any width (measured with search enabled) - Edition labels (Cloud, Enterprise, Sandbox, Open Source) at full size on their own line - Copy button on code blocks and on standalone code snippets (addresses, commands), shown on hover, keyboard focus and always on touch screens, with a screen reader announcement when copied Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1LoAGVHbV3q1xi4EEPGQw

calebthings · 2026-10-26T14:11:57Z

It looks like an improvement on the previous website.

doc/static/pagefind/ fragments look like some local directory added by accident. It might be worth it adding that dir to .gitignore if they're generated on each local build.

Pagefind: Removed from the commit and added /doc/static/pagefind/ to .gitignore, thanks.

KrishnaIyer

@happyRip's review is pretty complete.

calebthings requested review from KrishnaIyer, happyRip and vlasebian as code owners October 23, 2026 12:33

calebthings marked this pull request as draft October 23, 2026 12:35

vlasebian requested a balanced review from Copilot October 23, 2026 12:48

Copilot started reviewing on behalf of vlasebian October 23, 2026 12:49

View session

Copilot AI reviewed Oct 23, 2026

View reviewed changes

Comment thread doc/themes/the-things-stack/assets/css/common/code.scss Resolved

Comment thread doc/themes/the-things-stack/assets/css/common/typography.scss Resolved

Comment thread doc/themes/the-things-stack/assets/css/highlight.scss Resolved

calebthings force-pushed the doc/brand-tokens branch from da75a62 to 2b93926 Compare October 23, 2026 13:07

calebthings marked this pull request as ready for review October 23, 2026 13:08

happyRip reviewed Oct 26, 2026

View reviewed changes

calebthings self-assigned this Oct 26, 2026

calebthings force-pushed the doc/brand-tokens branch from 2b93926 to 48e7203 Compare October 26, 2026 14:09

calebthings requested a review from happyRip October 26, 2026 14:12

happyRip approved these changes Oct 27, 2026

View reviewed changes

KrishnaIyer approved these changes Oct 28, 2026

View reviewed changes

calebthings merged commit 863cd29 into TheThingsIndustries:master Oct 28, 2026
1 check passed

calebthings deleted the doc/brand-tokens branch October 28, 2026 10:41

calebthings mentioned this pull request Oct 28, 2026

doc: Fix accessibility issues in docs theme #1502

Open

4 of 5 tasks

Navigation Menu

Repository navigation

doc: Align docs theme with TTI brand guidelines and drop TTUI - #1500

doc: Align docs theme with TTI brand guidelines and drop TTUI#1500
calebthings merged 1 commit into
TheThingsIndustries:masterfrom
calebthings:doc/brand-tokens

calebthings commented Oct 23, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

happyRip left a comment

Uh oh!

happyRip Oct 26, 2026

Uh oh!

happyRip Oct 26, 2026

Uh oh!

calebthings Oct 26, 2026

Uh oh!

happyRip Oct 26, 2026

Uh oh!

calebthings Oct 26, 2026

Uh oh!

calebthings commented Oct 26, 2026

Uh oh!

KrishnaIyer left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		<link rel="icon" type="image/png" sizes="64x64" href="{{ "favicon.png" \| relURL }}">
		<link rel="icon" type="image/png" sizes="120x120" href="{{ "favicon-120.png" \| relURL }}">

Conversation

calebthings commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Screenshots

Changes

Notes for Reviewers

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

happyRip left a comment

Choose a reason for hiding this comment

Uh oh!

happyRip Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

happyRip Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

calebthings Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

happyRip Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

calebthings Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

calebthings commented Oct 26, 2026

Uh oh!

KrishnaIyer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

calebthings commented Oct 23, 2026 •

edited

Loading