Film

The Film Design Language — an opinionated, modern web component library built with Lit. Its layout components follow the Every Layout primitives, and every size is a step on a single modular scale so the whole UI stays in proportion.

Install

npm i @mk/film lit

Usage

import '@mk/film'          // registers every <film-*> element
import '@mk/film/css/themes/default/index.css'

<film-stack>
  <film-box>
    <p>A box in a stack.</p>
  </film-box>
  <film-button>Click me</film-button>
</film-stack>

Individual imports (tree-shaking)

The package ships as preserved ES modules, so you can import only what you use:

import '@mk/film/actions/button'   // registers just <film-button>
import '@mk/film/layout/stack'

React

Typed React wrappers (generated with @lit/react) are available at @mk/film/react:

import { FilmButton, FilmDialog } from '@mk/film/react'

<FilmButton invert onClick={save}>Save</FilmButton>

Tooling

A Custom Elements Manifest (custom-elements.json) is published for IDE autocomplete and documentation tooling.

Attribute warnings

A mistyped attribute or value on a Film element would otherwise be ignored without a sound, and look like a styling problem. Film logs a console warning once for each distinct mistake instead:

film-cluster has no "variant" attribute, so it is ignored.
film-button: "primray" is not a valid variant; expected one of: primary, neutral, accent, success, warning, danger.
film-text: "1.5rem" is not a valid size; expected a value matching /^s-?[0-5]$/.

Only plain-word attribute names are checked, so aria-*, data-* and framework-generated attributes (_ngcontent-…, data-v-…, x-data) never trigger one. The warnings stay on in production builds, since a wrong value is a bug there too. To silence them:

import { setFilmWarnings } from '@mk/film'
setFilmWarnings(false)

Components

Layout (src/layout)

| Element | Purpose | | ---------------- | ----------------------------------------------------------- | | film-stack | Even, scale-based vertical spacing between children. | | film-box | Padded, bordered box (invert). | | film-center | Horizontally centres content within --measure. | | film-cluster | Wrapping row of items with an even gap (space, justify, align). | | film-sidebar | Two-part sidebar/content layout that collapses when tight. scroll="start\|end\|both" gives a pane its own scrollbar (needs a bounded host height). | | film-grid | Auto-fit responsive grid (min, space). | | film-switcher | Row that flips to a stack below a threshold (or limit). | | film-cover | Fills a min height and centres content, with top/bottom. | | film-frame | Crops slotted media to a fixed ratio. | | film-reel | Horizontally scrolling, snap-aligned strip. | | film-imposter | Overlays content centred on a positioned ancestor. | | film-icon | Sizes a slotted SVG to the adjacent text. | | film-split-panel | Two panes with a draggable, keyboard-operable divider. |

Actions (src/actions) — film-button (variant, size, form-associated type), film-button-group, film-icon-button, film-link, film-copy-button.

Typography (src/typography) — film-heading, film-text, film-prose, film-divider, film-visually-hidden, film-kbd.

Forms (src/forms) — form-associated controls (participate in a native <form> via ElementInternals): film-input, film-textarea, film-number-input, film-search, film-select / film-select-option, film-combobox, film-checkbox, film-radio / film-radio-group, film-switch, film-range, film-slider, film-color-picker, film-date-picker / film-calendar, film-file-input. Plus film-field (label/hint/error wrapper) and film-form (validation + submit).

Navigation (src/navigation) — film-breadcrumb / film-breadcrumb-item, film-menu / film-menu-item (with flyout submenus), film-menu-bar / film-menu-bar-item, film-tabs / film-tab / film-tab-panel, film-tree / film-tree-item, film-pagination, film-steps / film-step, film-nav / film-nav-item.

Overlays (src/overlays) — film-dialog and film-drawer (native <dialog> top layer), film-dropdown, film-tooltip, film-popover and film-popconfirm (Popover API + a hand-rolled positioning helper).

Windowing (src/windowing) — film-window (non-modal, stackable, draggable/resizable panel, not top-layer) and film-workspace (its container: z-order, focus, floating with drag-to-snap, and grid or recursive-BSP tiling). Built on the exported DragController.

Data (src/data) — film-card (with media / footer slots), film-avatar, film-details, film-accordion / film-accordion-item, film-list / film-list-item, film-code, film-table (data-driven, with optional sorting / selection (row-key keeps it across refetches) / sticky header / row virtualisation / activatable rows / custom cell renderers).

Feedback (src/feedback) — film-alert, film-badge, film-tag (variant, removable), film-progress-bar, film-spinner, film-skeleton, plus film-toast + the imperative toast(message, options) helper.

See ROADMAP.md for planned components and features.

Modular scale

Sizes come from CSS custom properties --s-5 … --s5, generated from a single --ratio. The scale uses the CSS pow() function where supported and falls back to a calc() chain everywhere else. Override the whole system by setting --ratio and --s0 on :root.

space vs size

Two conventions sit next to each other, and both now accept either form:

• size on typography (film-text, film-heading) takes a scale step — size="s1" — which the component expands to var(--s1).
• space on the layout primitives (film-stack, film-cluster, film-grid, film-sidebar, …) is a CSS length, passed straight through to a custom property.

space="s0" used to produce the invalid declaration gap: s0, which the browser dropped silently, leaving the default gap and looking like a styling bug rather than a typo. Bare scale steps are now resolved for every scale-valued property, so these are equivalent:

<film-cluster space="s2">…</film-cluster>
<film-cluster space="var(--s2)">…</film-cluster>

Anything that isn't a bare step (1rem, 0, auto, clamp(…), a var()) is still passed through untouched.

Forms

Film's form controls are form-associated via ElementInternals, so they submit by name, take part in constraint validation and respond to reset — in a plain <form>, with no wrapper needed:

<form>
  <film-input name="email" label="Email" type="email" autocomplete="username" required></film-input>
  <film-input name="password" label="Password" type="password" autocomplete="current-password"></film-input>
  <film-button type="submit">Sign in</film-button>
</form>

film-button is form-associated too: because its real <button> lives in the shadow root the browser can't associate it with a light-DOM <form>, so it drives the form itself. type="submit" calls requestSubmit() and type="reset" calls reset(). Enter inside a film-input submits, as it would in a plain <input>. Set autocomplete (username, current-password, …) so password managers recognise a sign-in pair.

Dates

Two ways in, for two different jobs:

• film-input type="date" — a real text field, so the date is typeable and gets the platform's own picker and keyboard entry. Quickest for a date far from today. The rest of the family (time, datetime-local, month, week) works the same way.
• film-date-picker — a trigger plus a film-calendar in a popover, for choosing a date near today by eye.

Both take min / max. On film-input these are forwarded to the inner input and enforced by the browser's own constraint validation, so an out-of-range value fails checkValidity() and blocks submission rather than being decorative:

<film-input name="as-at" type="date" label="Readiness as at"
            min="2020-01-01" max="2026-12-31"></film-input>

film-calendar's header steps by year (« ») as well as by month (‹ ›), with Shift+PageUp / PageDown for the same from the keyboard — a date six years back is a handful of clicks rather than one per month. Both stop at min / max instead of wandering into a fully disabled month.

film-form is the alternative, for collecting values without a native form. It aggregates the slotted controls, exposes getValues() / submit() / reset() and fires film-submit, film-invalid and film-reset:

<film-form @film-submit=${(e) => save(e.detail.values)}>
  <film-input name="email" label="Email"></film-input>
  <film-button type="submit">Sign in</film-button>
</film-form>

Inside a film-form, that component owns submission and film-button stands down, so the two never both fire.

Theming

Film is themed entirely through CSS custom properties — because custom properties inherit through the shadow DOM, anything you set on :root (or any subtree) reaches every component. All colours are authored in oklch.

There are three layers:

1. Palette (--film-palette-*) — raw oklch primitives. Internal; don't reference these directly.
2. Semantic tokens (--film-*) — the theming API. Components only ever read from this layer.
3. Components — consume the semantic tokens.

To retheme, override the semantic tokens:

:root {
  --film-color-primary: oklch(0.72 0.15 250);
  --film-color-link: oklch(0.55 0.16 250);
  --film-color-danger: oklch(0.9 0.06 25);
  --film-radius: 0.25rem;      /* squarer corners everywhere */
  --film-font-sans: "Inter", system-ui, sans-serif;
}

The main tokens:

| Token | Purpose | |---|---| | --film-color-text / --film-color-text-muted | Body text / secondary text | | --film-color-background / --film-color-surface | Page / component surfaces | | --film-color-border | Borders and dividers | | --film-color-primary (-hover / -active / -text) | Buttons / accents | | --film-color-inverted-surface / --film-color-inverted-text | Dark-on-light pairs (inverted Box, tooltips, badges…) | | --film-color-link / --film-color-focus | Links / focus rings | | --film-color-info / -success / -warning / -danger | Status surfaces | | --film-radius-sm / --film-radius / --film-radius-lg / --film-radius-pill | Corner radii | | --film-shadow-1 / --film-shadow-2 (--film-shadow-color) | Elevation for floating surfaces | | --film-overlay-scrim | Modal/drawer backdrop | | --film-disabled-opacity | Disabled-state opacity | | --film-z-sticky / --film-z-overlay / --film-z-toast | Stacking scale (non-top-layer elements) | | --film-duration-fast / --film-duration / --film-ease | Motion | | --film-font-sans / -serif / -mono | Font families |

Dark mode

The theme ships light and dark values via the CSS light-dark() function, so it follows the OS preference automatically. Force a scheme on any subtree with a data attribute:

<html data-theme="dark">   <!-- or "light" -->

Palettes

Colour palettes live in css/themes/default/application/palettes.css and are selected with data-film-theme (independent of the light/dark scheme). The default is paper; the rest are period film stocks:

| data-film-theme | Look | | --- | --- | | paper (default) | Warm neutral + terracotta accent | | classic | The original pastel cream + teal | | kodachrome | '60s Kodak — warm, saturated reds & golds | | polaroid | '70s SX-70 — faded creamy warmth, soft rounded corners | | ektachrome | '80s Kodak — cool crisp cyan-blue, sharp corners | | velvia | '90s Fujichrome — ultra-saturated emerald + punchy chroma |

<html data-film-theme="kodachrome" data-theme="dark">

Each palette only overrides the --film-color-* roles (and, for some, the corner radius), so adding a new one is a single CSS block. That file is the config a theme picker can enumerate.

Every palette meets WCAG AA contrast in light and dark mode — text, links, muted text, button states, status surfaces and focus rings — and src/internal/palette-contrast.test.ts checks it on every test run. It's self-contained, so to hold a palette of your own to the same bar, copy it into your project and add your palette's id to its PALETTES list. In dark mode the accent buttons carry dark text on a light fill, and hover/pressed lighten rather than darken, so the text stays readable in every state.

Writing your own Lit components

Most apps built on Film also write their own Lit elements around it. Two language pitfalls come up constantly there, and both fail far from the cause.

Backticks inside css and html templates

Styles and templates are tagged template literals, so a backtick anywhere inside one — including in a comment — ends the template early. Commenting a rule with the element it concerns is the natural thing to reach for, and with Film element names all over your styles the temptation is constant:

static styles = css`
  /* `film-cluster` owns the gap */   // ← terminates the template here
`

The resulting syntax errors point at whatever follows, often far below the cause. Write the name without backticks in CSS and HTML comments, or escape it (\` ). JSDoc comments sit outside the template and are unaffected.

Property names that HTMLElement already uses

A Lit element is an HTMLElement, so a reactive property named title, id, hidden, role, slot, lang, dir, style, part, popover, inert — or a method name like remove, focus or click — collides with the built-in one. How it fails depends on the declaration:

• Private, or a different type (@state() private title, @property() hidden = 0): TypeScript reports TS1238: Unable to resolve signature of class decorator at the decorator. The real cause is the error listed right after it — TS2415: Class '…' incorrectly extends base class or TS2416: Property '…' is not assignable — which names the field.
• Public, same type (@property() title = ''): it compiles, and silently takes over the native property — here the browser tooltip that title drives.

Pick a name that says what it's for instead: heading, panelRole, isHidden. Film follows the same rule (its popover controller field is called floating because popover is taken).

Troubleshooting

A fix doesn't seem to have landed after upgrading

Dev servers that pre-bundle dependencies can keep serving the old copy of Film after an upgrade: Vite keeps them in node_modules/.vite/deps/. The package on disk is new; the browser runs the old components, and every symptom looks like a Film regression.

Check which version the page actually loaded — every copy of Film that runs records itself on a global, so in the browser console:

filmVersions   // ['1.4.0']

If that's older than the installed package, clear the cache and restart — rm -rf node_modules/.vite, or start Vite with --force. Two entries mean two copies of Film are loaded, which usually has the same cause. You can also read the version in code:

import { version } from '@mk/film'

Development

npm install
npm run dev        # start the Vite dev server (demo site)
npm run typecheck  # type-check with tsc
npm run build      # build the demo site into dist/
npm run build:lib  # build the publishable library into dist/

Written in TypeScript with Lit decorators. The library source lives in src/ (grouped into layout, actions, typography, forms, navigation, overlays, data, feedback, with shared internals in internal), the demo site in demo/, and the theme/scale CSS in css/ (palette in definitions/colors.css, semantic tokens in application/theme.css). Every component extends FilmElement; form controls extend FilmFormControl. The pitfalls under Writing your own Lit components apply to Film's own source too.