Reference

Contributing

For contributors changing the framework itself: build the package from its TypeScript sources, follow the three conventions, and get a merge request accepted.

Setup

The repository holds the npm package in rikiki/ and this site insite/. The commands below are the package's own scripts, so they run from rikiki/.

terminal

git clone https://gitlab.com/tordu-jardin/rikiki.git
cd rikiki/rikiki     # the npm package · every command below runs from here

npm ci
npm run build        # vendor chunks, esbuild, standalone bundle, then tsc --emitDeclarationOnly
npm run watch        # esbuild in watch mode, for iterating on a deck
npm run typecheck    # tsc --noEmit
npm test             # vitest run · sizes, versions, CLI and assembler
npm run lint         # biome check src scripts tools

npm run new:component -- text deck-myname   # scaffolds a conforming component

npm run build runs four steps in order: build-vendor.mjswrites the local Lit and marked chunks, build.mjs compiles everysrc/**/*.ts entry point, build-standalone.mjs emits the single-file runtime, and tsc --emitDeclarationOnly writes the.d.ts files.

dist/ is versioned · the zero-build promise applies to deck authors, not contributors. Commit the rebuilt dist/ with your source change so consumers don't need to run anything.

Conventions

English for code, comments and commit messages.
No magic numbers in CSS · sizes, colors and spacing route through the theme tokens (--rik-space-*,--rik-font-size-*, --rik-surface-*,--rik-text-*), defined in themes/rikiki.css andthemes/siliceum.css and reached throughtokens.css.
No em-dash in prose, slide content or source files · the middle dot ( · ) replaces it, and npm run lint:dashes insite/ fails on any that slips in.
Read MANIFESTO.md first before proposing a feature · the rejected-features list saves time.

Adding a component

Pick the bucket · layouts/ for slide-level, molecules/ for containers and composed elements, atoms/ for primitives, runtime/ for orchestration code that isn't part of the author-facing API.
Create src/<bucket>/deck-myname.ts.
Extend LitElement, decorate with @customElement and @property.
Expose per-component tokens with sensible defaults from the theme palette · users should be able to retheme via --deck-myname-*.
Register it in src/index.ts with the full bucket path: import './<bucket>/deck-myname.js'.
Run npm run build · commit both src/ and dist/. The compiled JavaScript stays flat regardless of the bucket, so the public URL is /rikiki/dist/deck-myname.js; only the .d.ts files mirror the source folders.

src/<bucket>/deck-myname.ts

// src/text/deck-myname.ts  (a family: layout, structure, text, data, media)
import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('deck-myname')
export class DeckMyname extends LitElement {
  static override styles = css`
    :host { display: block; padding: var(--rik-space-3); }
  `;

  @property({ type: String }) tone?: string;

  override render() {
    return html`<slot></slot>`;
  }
}

declare global {
  interface HTMLElementTagNameMap {
    'deck-myname': DeckMyname;
  }
}

Merge requests

The project is hosted on GitLab, so a change arrives as a merge request against main.

One self-contained change per merge request.
Include a short rationale · what changed, why, what was considered and rejected.
If the change is visual, attach a before/after screenshot.
npm run build must succeed, npm run typecheck must stay at 0 errors, and npm test must pass.
If the change touches a component, run the deck checks on a deck that uses it (npx rikiki check decks/tests/demo.html) and read the report · see Check & deliver.

Bundle budget

Two budgets are declared in scripts/size-surfaces.mjs and enforced by npm test: 45 KB gzip for the initial load (dist/index.js plus the Lit and marked chunks it imports, which is what a browser downloads before the first slide paints) and55 KB gzip for dist/standalone.js. The current build measures 43 KB and54 KB. Mermaid and Shiki sit outside both figures: they are optional modules a deck imports only when it uses them.

A change that eats into the remaining headroom needs a reason in the merge request · the alternative is to move the code into an optional module (deck-overview.js and deck-help.js are the precedent). Crossing a budget is a decision to document, not a number to raise quietly.

To measure your change: