design-system-example-components-react: the Digital Agency design system as React code

What the repository is: reference code for a government design system

The Digital Agency of Japan publishes a design system, and this repository is its sample component set in React. The project README describes it as a collection of samples implementing the Digital Agency design system with React and Tailwind CSS, and the repository is published to npm under the scoped name @digital-go-jp/design-system-example-components-react.

That framing explains the shape of the project better than the word component does. The listed features are compliance with the Digital Agency design system, minimal dependencies, customisability and a simple implementation. There is no marketing about developer experience or a theming engine. The audience is a specific one: teams working on Japanese government services who need their interface to follow the agency's rules, and React developers who want to see how those rules look in code.

The components cover a standard government form vocabulary. The directory listing under src/components shows an Accordion and a Blockquote among the entries, with the rest elided, and the naming follows familiar pattern. Alongside the components there is a docs directory, a tokens directory for design tokens, and a root index.ts that exports every component.

Each component directory follows a fixed three-file convention, documented in the README: a .tsx file with the component itself, a .stories.ts file with the Storybook story, and an index.ts that re-exports it. That consistency is the thing that makes the collection usable as a reference, since every component is laid out the same way and you can read one to understand the rest.

Design tokens arrive as a Tailwind plugin, not as hard-coded values

The tokens are where a design system either works or becomes a set of screenshots. This project takes the first route. The README states that the samples use a Tailwind CSS plugin based on the Digital Agency design system design tokens, and it asks you to install a specific package into your project when you use the snippets:

npm install @digital-go-jp/tailwind-theme-plugin

The plugin in question is @digital-go-jp/tailwind-theme-plugin, and the package metadata shows it as a direct dependency alongside @digital-go-jp/design-tokens, with react, react-dom, tailwindcss and react-aria-components also listed as runtime dependencies.

That dependency list is worth reading closely, because it explains the implementation choices. react-aria-components is the accessibility and behaviour layer, and @internationalized/date handles internationalised date handling, which matters for a government service that must accept dates in Japanese formats. react and react-dom sit at 18.3.1 and tailwindcss at 3.4.19.

The practical point is that the visual values in the components are not arbitrary. They come from the token set through the plugin, so a design decision made by the agency propagates to your interface without a designer hand-editing hex values in a component. The cost is a hard coupling to the token package version, and the token packages are versioned separately from the component package, so an upgrade of one is not automatically an upgrade of the other.

React 18 is the target, and React 19 will show type errors

There is a compatibility caveat, and the README is upfront about it. The samples are implemented on React v18. If you bring them into a React v19 project, minor type errors may appear, and the README asks you to fix them as needed. It also says an update of the snippets to React v19 is under consideration.

Under consideration is not scheduled. For a team on React 19 today, that means the type friction is yours to absorb, and it is spread across every component you copy rather than concentrated in one place.

The wider stack follows the same pattern. The README lists React v18, Tailwind CSS v3 and TypeScript as the technical stack, so this is a Tailwind v3 project, and the dependency list confirms tailwindcss at 3.4.19. A team that has moved to Tailwind v4 is not going to get the plugin's behaviour for free.

None of this makes the components unusable, and the reasons to accept the friction are real: the components already encode the agency's accessibility and interaction decisions, and reimplementing those is a larger cost than fixing a type error. But the compatibility picture is a fact to plan around rather than discover.

Storybook is both the documentation and the local review workflow

The README states that component behaviour, styles, usage and implementation notes can all be checked in the Storybook for the React code snippets, and the hosted Storybook lives at design.digital.go.jp/dads/react. That means the documentation is executable rather than a set of markdown pages, which is the right choice for a component collection whose whole purpose is to show behaviour.

The same guide runs locally. The README describes three steps: clone the repository with any method you prefer, install the dependencies, and start Storybook. The install and start commands are:

npm run storybook

The Storybook dev server listens on port 6006, and the README points you at http://localhost:6006 to review every component. The package metadata confirms the port in the scripts section, where the storybook entry is storybook dev -p 6006 and a separate build entry produces a static bundle.

The npm scripts show the rest of the workflow. There is a build step that runs tsc and then vite build, formatting and linting through biome, and a markup lint that runs markuplint over the jsx and tsx files in src, which is how the project checks accessibility markup on its own components.

The test setup is layered. A general test script runs vitest in run mode, while separate project scripts target storybook and unit tests, and a setup script installs chromium through playwright. That is a browser-based test arrangement, so the test cycle is slower than a pure unit test suite, and the chromium download is a first-run cost.

The npm package is a real library, not just a documentation site

It is easy to mistake this repository for a documentation site with code samples. The package metadata says otherwise. The package is versioned 2.7.0, is marked as an ES module, and publishes three build outputs: a CommonJS entry at dist/index.cjs.js, an ES module entry at dist/index.es.js, and type declarations at dist/index.d.ts. The exports map points consumers at those files, and the published files list is limited to dist.

So you can install the components and import them, rather than copying source into your repository. That matters for maintenance, because a published version can be upgraded on a schedule instead of tracked file by file.

The release tags follow a date-based scheme rather than semver: v20260909, v20260819 and v20260805, all published on 2026-10-15. The version number in package.json is separate again, at 2.7.0. If you track the design system closely, the date tags tell you exactly which snapshot of the design system a given build corresponds to, which is the kind of thing that matters when an agency's design decisions change on a schedule tied to its own release cycle.

The last push to the repository was on 2026-10-21, and the repository is not archived, so the snapshot is a moving target rather than a finished artifact.

Issues are welcome, pull requests are not being taken

The contribution policy is narrow and worth reading before you plan around it. The README asks you to report bugs and feature requests by creating an issue, and states that pull requests are not accepted at the moment.

That is a real constraint on adoption. A component collection you cannot patch is a component collection you either take as is or fork. If you need a behaviour change, your options are an issue and waiting, or a private fork. The upside of the policy is that the sample set stays aligned with the agency's own design decisions rather than accumulating outside contributions, which is the point of a reference implementation.

The licence is MIT, and the README states the snippets are published under it, with a LICENSE file at the repository root and the same identifier in the package metadata. MIT permits modification and redistribution, including in commercial products, provided the notice travels with the code. For a reference implementation that many teams will copy parts of, that is a permissive and workable arrangement.

The repository also carries an AGENTS.md file and a .agents directory, which suggests instructions for automated coding agents are part of the project's setup. There are editor configuration files, a .markuplintrc for the markup linter, a biome.json for formatting and lint rules, and a vite configuration for the build.

Where this collection stops and another approach starts

The realistic alternative is to use the design tokens without these components. The token package and the Tailwind plugin are published independently of the component collection, so a team that wants the agency's colours, spacing and typography in its own component library can take the tokens and build components its own way. The difference in approach is where the accessibility and interaction work lives: this repository has already made those decisions and encoded them, while building your own means you own the behaviour, the keyboard support and the markup, using the same visual source.

For a government service with in-house React engineers and existing form components, that trade is often worth taking. For a team without the time, the samples are the shortcut, and the fact that they are accompanied by Storybook notes on implementation cautions gives you more than screenshots.

The case where this collection is the wrong tool is a product outside Japanese government services that happens to like the look. The design decisions encode rules for a specific context, and the naming, the component set and the tokens all follow that context. A general product would inherit a set of constraints it did not ask for.

One more limit deserves naming. The README does not document a changelog, a migration guide between versions, or a policy for deprecating a component. With releases named after dates and a package version that moves independently, an upgrade that changes a component's markup is something you would find out about from the Storybook diff, not from release notes.

Editorial conclusion

design-system-example-components-react suits teams building Japanese government services that need components conforming to the Digital Agency design system, and for React developers who want a concrete Tailwind and React Aria reference. It is the wrong choice for a product that needs design tokens it can reshape freely, for teams on React 19 who cannot absorb the documented type errors, or for anyone hoping the repository will accept their patches, because pull requests are not being taken at present. Before adopting it, read the component notes in the Storybook, install the @digital-go-jp/tailwind-theme-plugin the README asks for, and check the version of the design tokens package your product actually pins.

Frequently asked questions

Official sources

1. digital-go-jp/design-system-example-components-react on GitHub
2. License: MIT
3. Project website
4. README
5. Releases