Skip to content
opsinjs
Edit this page

opsinjs

Styling

Style a component you own through className, its data attributes and the render slot, without breaking the theme or the colour axes.

Installed components are source you own, so you can edit them, but each edit is yours to merge at every upgrade. Try these hooks first, and fix the token in Theming when several components look wrong the same way.

className and style

Every component takes className and merges it onto its root with cn(), which is clsx plus tailwind-merge. Your class comes last, so it wins a conflict:

import { cn } from "@/lib/utils"

cn("px-4 py-2", isWide && "px-8")
// "py-2 px-8"
  • className styles only the root of what receives it, such as Card or Card.Header. Reach anything else through its data-slot.
  • When you wrap a component, forward className last, or the default overwrites the caller's.
  • The registry does not ship cn, so yours is the one shadcn init wrote. Its stock tailwind-merge treats text-opsin-* type steps as colours, so cn("text-opsin-body", "text-foreground") keeps only the later class. Write the colour as [color:var(--foreground)], as the components do.
  • Most components take a closed set of props with no style. Button and Link forward their native element's attributes, style included.
  • Never hardcode a colour such as bg-[#e11d48] or a size such as text-[13px], never reach for !important, and never style into a component's internals by descendant selector.

Data attributes

Attributes are the styling and testing contract, so renaming one is a breaking change. opsinjs stamps a closed set of four:

AttributeOnValue
data-slotEvery part of every componentThe part, such as result-card-header
data-statusAn element whose colour, icon or word carries a statussteady, watch, attention, urgent or unknown
data-categoryAn element tinted from the category axisOne of the six categories
data-opsinjs-valueAn element showing a measurementThe unrounded number, without its unit, so never export it alone
[data-open] { /* the popup is open */ }
[data-status="urgent"] { /* the value's clinical status */ }

Components built on Base UI add its state attributes, such as data-open, data-disabled and data-starting-style. These are present or absent, so [data-open] matches and [data-open="true"] does not.

  • Style a state through its attribute, not a class you toggle.
  • Never set data-status yourself to force a colour, because that puts a clinical claim in the DOM that nothing backs.
  • Never invent data-opsinjs-* attributes. Use your own prefix.
  • No data-state attribute exists, so a selector against it matches nothing.

The render slot

Four components take render, an element rendered in place of their own. Link, Card and MetricTile take your router's link so navigation stays client-side, and Field.Control in Field takes a control opsinjs does not ship, such as <textarea rows={3} />. Link's own href, data-slot and attributes win over the router element's, and the two class lists are joined.

import NextLink from "next/link"
import { Link } from "@/components/ui/link"

<Link href="/results" emphasis="action" render={<NextLink href="/results" />}>
  See your results
</Link>

Button takes no render, href or as, because a control that goes somewhere is a Link. render is the nearest thing to shadcn/ui's asChild, and it is untested against Next and React Router links.

Naming

ThingConventionExample
Component id, file and docs pathkebab-caseresult-card
ComponentPascalCaseResultCard
Props interface<Component>PropsResultCardProps
PropcamelCase, booleans positivedisabled, not isDisabled
Custom property--opsin-, then axis, member, role--opsin-status-urgent-surface

Prose is British and code is American. Never name anything normal, never use error for a clinical state, and never add a catch-all variant prop, which ends up carrying both axes.

TypeScript

Every component exports a <Component>Props interface, from which its page's API table is generated. The axis types ship with every component in lib/opsinjs.ts:

import { type ClinicalStatus, type HealthCategory } from "@/lib/opsinjs"

ClinicalStatus holds the four levels and HealthCategory the six categories. unknown is a separate UnknownStatus, the absence of a verdict rather than a fifth level, and ClinicalStatusOrUnknown joins the two. Type a wrapper with Pick and Omit on the exported interface, and never widen status to string.

Lint rules

NOT IMPLEMENTED. This component does not exist in any released version of opsinjs. There is no package to install, no module to import and no props interface to generate code against. Everything on this page is a specification of intended behaviour and may change without notice. Do not write code against it.

The opsinjs lint tooling is not built yet

eslint-plugin-opsinjs and stylelint-plugin-opsinjs are proposed as specifications. Neither is built or published.

PlannedRoadmapWhat “planned” means

Until they exist, review by hand for a colour literal or arbitrary colour value, both axes on one element, a status token in a category role, a banned word such as "normal" in copy, and a component variable set on :root. In a fork, pnpm run check:a11y catches several of these, but only in the component sources under registry/, never in your application.