Getting started

This guide explains how to run, customize and package DevSikt. It is an HTML-first Tailwind theme with TypeScript interaction examples, not a connected developer platform. A coding agent is optional: an editor, terminal and browser are enough.

Version and applicability

These articles describe DevSikt version 1.0.0. Use them with the files supplied in your download; paths and commands are relative to the extracted source root. See CHANGELOG.md for release notes.

Install and run

Open a terminal in the folder containing package.json. Check your tools before installing:

node --version
npm --version
npm ci
npm run dev

The installed Vite 7.3.6 release declares Node ^20.19.0 || >=22.12.0. This is more specific than “Node 20 or later”: use a version satisfying that range and recheck node_modules/vite/package.json when upgrading dependencies. npm ci installs the locked dependency versions and replaces an existing node_modules/ installation; it does not update the lockfile. Run it from the source folder with its matching package-lock.json, not inside dist/ or dist-docs/.

Open the local URL printed by Vite and keep that terminal running. Press Ctrl+C to stop it. To use the demo's usual port explicitly:

npm run dev -- --port 5200 --strictPort

Root HTML files are source entries. Shared partials, Tailwind and TypeScript require the development server or build process. Double-clicking source HTML in Finder is not a supported preview workflow.

Choose the right files

• Source folder with package.json, package-lock.json and src/: follow the install steps above. Edit these files and rebuild.
• Compiled theme output from dist/: serve the complete folder over HTTP or upload its contents to a static host. No npm installation is needed just to view it.
• Standalone documentation output from dist-docs/: serve or publish this folder separately. It does not contain the application demos.

The build commands create the output folders; they are not substitutes for the editable source. Keep the source and lockfile if you expect to customize or rebuild later.

Explore the source

• Root .html files: page markup and module entry points.
• src/theme/css/: shared tokens and Tailwind styling.
• src/theme/ts/: shared shell behavior.
• src/project/css/ and src/project/ts/: customer styles and demo controllers.
• src/project/partials/: shared navigation and reusable example markup.
• public/: static files copied into the full theme build.
• docs/content/: these Markdown articles.
• tests/: browser interaction and accessibility checks.
• vite.config.ts: page entries and build-time HTML transforms.

Start with Customization before changing the visual system. Keep your original source in version control or a backup so customer changes remain distinguishable from future theme updates.

Make your first edit

Prerequisites: the editable source, a compatible Node version and a working local development server. This recipe applies to version 1.0.0. Exact file: root index.html.

1. Run the development server and open index.html.
2. In your editor, change the “Workspace overview” heading in the root index.html source. Keep its IDs and interactive controls intact.
3. Save and check the browser update. Use the narrow viewport and the appearance toggle as well as desktop.
4. Run the build and preview commands below. Confirm the same change appears in compiled output.

Expected result: your heading appears in development and the compiled preview without changing queue behavior. If nothing changes, check that you edited source rather than dist/, are viewing the server's current port, and saved the file. If the page is unstyled, use the Vite URL rather than double-clicking HTML. Restore the original heading after the exercise if you intend to run fixture-specific tests unchanged.

npm run build
npm run preview

Open the preview URL printed by Vite. dist/ contains the compiled theme; do not edit it to make permanent changes. No Node server is needed on the eventual static host, but serve the compiled files over HTTP rather than relying on file:// browser behavior.

Understand the preview

Names, projects, integrations and approvals are fictional. Chat responses are scripted. Sign-in buttons do not authenticate, and approval controls do not execute commands. Billing, invoice and invitation screens demonstrate presentation and local states, not payment processing or access enforcement.

Most demo changes reset on reload. Sidebar pins and collapsed groups use browser-local preferences. Artifact examples fetch bundled same-origin fixtures; upload examples do not transmit files. Read a page's notice and controller before replacing its sample behavior. Never use a client-side role, key or approval UI as authorization.

Validate changes

Install the test browser once, then run the complete check:

npx playwright install chromium
npm run check

The check runs distribution-validator unit tests, builds the theme and standalone documentation, validates their local references and output boundaries, then runs the browser suite. A focused run is useful while editing an existing feature:

npm test -- tests/invoice.spec.ts

Run checks serially: the browser suite uses port 5198, and documentation tests expect build output. Review keyboard operation and 390×844, 768×1024 and 1440×1000 in light and dark appearances. Automated accessibility checks do not replace manual screen-reader or cross-browser review. See Troubleshooting for environment and preview failures.