Customization

Applies to DevSikt 1.0.0. Prerequisites: a running development server, the matching lockfile and a source backup. The exact paths below are relative to the extracted source root.

Keep customer-specific work separate from shared theme code. DevSikt uses Tailwind utilities and CSS custom properties; it does not use Bootstrap or a frontend application framework.

Change colours and typography

Inspect src/theme/css/tokens.css for semantic roles and the @theme inline utility mapping. Customer overrides belong in src/project/css/project.css:

/* Radius applies to both appearances. */
:root {
  --dd-radius: 0.25rem;
}

/* Replace example values with your approved, contrast-tested palette. */
:root:not([data-theme="dark"]) {
  --dd-accent: #8b4e08;
  --dd-tint: #fbefd9;
}

:root[data-theme="dark"] {
  --dd-accent: #efbf79;
  --dd-tint: #3b2e1d;
}

Use semantic classes such as bg-surface, text-ink, text-muted and border-line. Do not scatter brand hex values through page markup. Match dark selector specificity rather than assuming a plain :root override will win. Radius tokens style shared primitives; explicit Tailwind rounding utilities in markup are separate choices, so audit them when changing the radius system.

For a project font override, add an @theme font definition in project CSS and use the matching utility. Supply properly licensed font files, loading declarations and fallback fonts if needed; changing a family name alone does not install a font. Inspect long labels, numbers and both appearances after any typography change.

Edit pages and navigation

Root source entries use build-time partials:

{{> sidebar}} {{> mega-menu}}

Names resolve to src/project/partials/sidebar.html and mega-menu.html. Use the exact placeholder syntax. The current transform replaces placeholders once; do not depend on nested partial expansion.

To add a workspace page manually:

1. Copy a relevant root HTML file to a new filename, for example reports.html. Retain the sidebar partial, #main, mobile navigation controls and the mega-menu header if its controller is imported.
2. Update the document title, description, breadcrumb, heading and page content. Remove sample controls you are not using, along with their controller imports.
3. Create src/project/ts/reports.ts and point the page's module script at it.
4. Add reports: "reports.html" to the non-documentation page entries in vite.config.ts, beside the existing dashboard and workflow entries. A file can work in development yet be absent from production if it is not registered.
5. Add a link to the relevant project partial and, when appropriate, the Jump to destinations in src/project/partials/sidebar.html. Navigation is not generated from Vite's entry list.
6. Build, preview the compiled page directly, and add interaction tests for its controls.

A standard workspace controller can start with:

import "../../theme/ts/index";
import "./account";

<script type="module" src="/src/project/ts/reports.ts"></script>

These imports expect the existing workspace shell markup: the theme controller uses #sidebar, #nav-open, #nav-close and #main; the account controller imports the mega menu, command palette and project groups. Do not use this controller unchanged for a shell-free authentication page. Inspect the closest existing page and its full import chain instead of importing a feature controller solely to obtain CSS.

Vite inserts the theme and project stylesheet links in the document head. Keep CSS in that pipeline rather than relying on a module import for first-paint styling.

Compose the working surface

The full development source (1.0.0) uses src/project/css/workspace-layout.css. On sidebar-based pages, retain dd-workspace on the body and place one dd-content-surface after the main header and before its footer. Do not wrap every subsection in another panel. Keep input boundaries, table separators, useful status icons and keyboard focus outlines.

Overview and Work queue use dd-queue-section instead of an extra wrapper. Full-page chat uses dd-chat-surface to retain transcript scrolling and composer access. Authentication and invoice pages keep their own layouts. Use --dd-rail for the surrounding canvas and --dd-surface for the content surface; change tokens, not repeated page-level colours.

After adapting a page, verify its content at all reference widths and in both appearances. Check menus and dialogs as well as the initial screen. A page that fits before opening a control may still overflow when it opens.

Update without losing your changes

For source-based customization, start with your current source, its matching lockfile, a backup or version-control checkpoint, and the new release's changelog.

1. Record your current version and separate customer edits in src/project/, root HTML and configuration from upstream theme files.
2. Extract the new release into a separate directory. Never overwrite your only working copy or copy a new dist/ over editable source.
3. Compare the two versions. Merge relevant shared theme/build changes, then reconcile customer markup, controllers and overrides. The source boundary aids comparison; it is not an automatic merge guarantee.
4. Use the new release's matching manifest and lockfile when adopting its dependency set. Review new build requirements before installing.
5. Run the documented install/build/check commands in the separate copy and exercise your customized pages. Check light/dark, keyboard behavior, links and exports.
6. Deploy the complete matching compiled output only after review. Retain the prior source and deployment for rollback.

Expected result: your customer changes survive while the selected upstream changes pass validation. If selectors or controller IDs changed, resolve the documented contract rather than suppressing test failures. Do not mix hashed assets from different builds.

Add customer behavior

Place interactions in src/project/ts/, using native buttons, forms, details and dialogs where possible. Keep visible labels, accessible names, focus restoration, validation messages, loading cancellation and empty/error states with the control you copy. Insert user-controlled text with textContent, not HTML strings.

Avoid dynamically assembling Tailwind class fragments such as "bg-" + color. Keep complete class names in scanned source, or use a semantic token for runtime values. Tailwind scans the configured source, not the browser's eventual DOM.

Changes in src/theme/ affect every consuming page and need broader regression review. Put page-specific styling in project CSS, scoped to that page's class. Import project CSS modules from src/project/css/project.css so the shared head stylesheet pipeline includes them before JavaScript runs; do not rely on deferred JavaScript to supply first-paint styling.

Add images and static files

For a fixed public file, place it under public/assets/ and reference it from a root page as assets/example.webp. The full build copies public/ contents into the output root. Do not write public/assets/... in the browser URL.

Use relative page links such as reports.html, not /reports.html, when the finished site may live under a path prefix. Asset paths referenced from nested pages must account for their directory. Source module entry paths are processed by Vite; do not manually rewrite generated hashed asset URLs.

Provide dimensions and meaningful alternative text for informative images; use empty alternative text for purely decorative ones. Record source and licence before redistributing any image, icon or font. The standalone documentation build deliberately excludes public/, so do not assume a newly added public asset will exist there.

Review responsive behavior

Test real-length headings, empty data and errors at 390×844, 768×1024 and 1440×1000. Tables and code may scroll inside labelled, keyboard-accessible regions; the whole document should not scroll sideways. Test touch access to hover controls, visible focus, dialogs with Escape and return focus, both appearances and reduced-motion preferences.

The workspace and documentation sidebar is a drawer below 1024 CSS pixels. Keep the lg:ml-60 content offset, navigation trigger visibility, CSS breakpoint and TypeScript media query aligned when adapting the shell. Compact workspace headers retain an accessible “Components & pages” name when the menu trigger becomes icon-only on phones; authentication headers keep their separate centered-logo layout.

The full-page chat uses src/project/css/chat-layout.css to keep its transcript scrollable and its composer in view. History and demo controls open over the workspace instead of pushing the composer down. Preserve access under increased text spacing, short viewports and software keyboards; the reference viewport tests do not prove behavior on every physical device. Overview and queue controls use a native “Filters & options” disclosure; bulk actions appear only after selection and restore focus when cleared.