Language for UI's

A native DSL for accessible interface decisions.

Language for UI's

Valence is the Web Component design system behind Portfoliable.js. Built in Storybook, it uses native custom elements instead of tying the system to a single framework. A component can be consumed by Portfoliable today and remain available to another JavaScript application tomorrow.^[1][2]

The components encapsulate behavior and styles through Shadow DOM. Application styles do not accidentally rewrite a button, and a component can evolve without requiring every consumer to copy its CSS. This also keeps the design system close to the browser’s native model—attributes, slots, events, and semantic HTML.

import '@portfoliablejs/valence';

const button = document.createElement('ds-button');
button.setAttribute('label', 'Open case');
button.setAttribute('variant', 'primary');
document.querySelector('#actions').append(button);

A structure that scales with the interface

The library follows an Atomic Design vocabulary, but uses it as an engineering map rather than a taxonomy for its own sake:

This separation makes changes easier to reason about. A spacing adjustment belongs to a token; a keyboard interaction belongs to the component that owns it; a reading-flow decision belongs to the consuming template.

Storybook as a development surface

Storybook is more than a catalog here. It is the place where a component’s API, edge cases, visual states, and accessibility behavior become inspectable. The Canvas gives immediate feedback; the Docs tab explains the contract; controls let a developer test real prop combinations without first wiring a full application.

export const Reflow = {
  args: {
    label: 'reflow',
    count: 3,
    background: '#7ED321'
  }
};

That workflow changes the feedback loop. Instead of asking whether a component works only inside a page, the team can ask better questions earlier: Does a long label reflow? Is the focus state visible? What happens when the count changes? Can the same API represent loading and disabled states?

Accessibility is a global capability

Valence treats accessibility as a system-level concern. The consuming application can toggle modes from the document root and let the component library respond consistently:

<html class="a11y-dark-mode a11y-focus-mode">
  <body>
    <ds-header></ds-header>
  </body>
</html>

In Storybook, these modes appear as global controls, allowing accessibility to be evaluated as part of normal development rather than only as a final audit. With Portfoliable, the runtime can handle user preferences and state, while Valence handles the visual response.

Integration without losing boundaries

Portfoliable consumes Valence through ordinary Web Platform contracts. Simple state travels through attributes; rich content enters through slots; user actions return as namespaced custom events:

<ds-case-view
  title-text="Designing a clearer onboarding flow"
  show-language-menu="true">
  <article slot="content">
    <h2>Outcome</h2>
    <p>The case narrative remains owned by the application.</p>
  </article>
</ds-case-view>

This division keeps responsibilities clear. Valence provides the interaction surface and visual language; Portfoliable provides case data, routes, localization, and product context.

The result

• A reusable foundation: components can be consumed by Portfoliable and other web applications.
• A shorter feedback loop: Canvas, Docs, and Controls make behavior visible early.
• Accessibility by construction: modes and interaction states are tested as part of the system.
• A clearer collaboration model: design decisions become tokens, APIs, and documented patterns.

Valence is the layer that allows Portfoliable to be coherent without making every case look the same. It turns interface craft into shared infrastructure while keeping it close to the open web.

What I would do differently

If I started Valence again, I would make some choices more explicit from the beginning:

• Define a performance budget: measure the cost of each component, style, and accessibility mode, and set limits for JavaScript, CSS, and fonts before the system grows.
• Establish governance earlier: document the process for proposing, reviewing, deprecating, and versioning components, tokens, and API changes.
• Test with a real context matrix: combine browsers, screen sizes, assistive technologies, motion preferences, and contrast modes in automated and manual tests.
• Be more deliberate about granularity: not every difference needs to become a component or property. Keep the API small to avoid combinations that are difficult to document and maintain.
• Validate components in real products earlier: use complete Portfoliable flows from the start instead of relying primarily on isolated states in Storybook.

These changes would not alter the project’s direction, but they would make its decisions more sustainable. The goal would be to preserve Web Component portability and accessibility as a global capability while reducing the system’s weight, complexity, and cost of evolution.

Explore the Valence repository or see how it supports the Portfoliable runtime.