A small CSS kit with one token contract, four themes (bulletin, report, reportage, slate) and one component set, so reports, bulletins and dashboards look related without copy-pasting styles.
Open-Source Tools · How-To · Dev & ops tools
How to use research-design-system: one set of design tokens, four themes for reports and dashboards
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/research-design-system
Watch the walkthrough
Watch on YouTube: youtu.be/W33FVHd4A3I
Why it is useful
- Who benefits: analysts and writers who publish reports, newsletters and dashboards and want a consistent look with almost no CSS work.
- What it replaces: re-copying styles between HTML pages, Blogger themes and one-off dashboards.
- Evidence from the run: the same report template rendered in all four themes by changing only the theme stylesheet and one body class; a screenshot of each was captured.
- Rules baked in: units in table headers, a source note on every exhibit, reading width capped at 68 characters, wide tables scrolling in their own container.
- Documents three real bugs it prevents: invisible text in dark mode, drop-caps from Blogger themes, and WeasyPrint print hangs.
What it is for
research-design-system consolidates design assets found across about 42 repos and two Blogger properties into tokens/tokens.css, four theme files, components/components.css and print/print.css.
The contract is that components only use semantic tokens (--c-text, --c-accent and so on). A theme just rebinds roughly a dozen of those tokens, so a new theme is a short file.
Templates for a report, a bulletin and a dashboard, a live component gallery in docs/index.html and an INVENTORY.md of the original assets are included.
Who it is for
- Analysts publishing HTML reports or bulletins
- Developers building a simple dashboard shell
- Anyone standardising a house style across several pages
- Pixel-exact brand work: it is a small starter kit, not a corporate brand system
- Pages that need JavaScript widgets: only CSS is provided
- Dark mode that follows the OS: dark mode is opt-in by design (data-theme="dark") and only theme-reportage models it fully
What you need
| Requirement | Why | How to get it |
|---|---|---|
| A web browser | to open the templates and the gallery | any modern browser |
| A text editor or an AI assistant | to copy a template and edit the text | VS Code, or Claude Code or Gemini CLI inside the cloned folder |
| Python 3 (optional) | the repo's Python tag is only for helper scripts; the kit itself is plain CSS | not needed to use the themes |
| WeasyPrint (optional) | to turn pages into A4 PDFs using print/print.css | pip install weasyprint (not run for this post) |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/research-design-system.git
cd research-design-system
claude # or: geminiInstall
- Clone the repo
git clone https://github.com/herrrickshaw/research-design-system.git cd research-design-system - Open the live gallery in your browser
open docs/index.html
Quick start: commands and what you should see
Start from a template and open it
cp templates/report.html my-report.html # then fix the ../ paths or keep the file inside the repo
open my-report.htmlA report page with masthead, in-brief card, stat tiles, a table exhibit, a side box and a warning box. The stylesheet links must be in this order: tokens, theme, components, print.
Switch theme
sed -i '' 's#themes/report.css#themes/slate.css#; s#theme-report#theme-slate#' my-report.htmlThe same content on a dark slate ground with blue accents. Use theme-bulletin, theme-report, theme-reportage or theme-slate.
Make your own theme
cp themes/report.css themes/mine.css # then rebind the --c-* tokensComponents pick up your colours because they never reference raw palette values.
Sample outputs
Real output from a run on the date shown in the sources line; trimmed to fit.
Four themes on the same template (rendered 19 Oct 2026 with headless Chrome, 1000 px wide)
templates/report.html with themes/{bulletin,report,reportage,slate}.css
bulletin.png 138 KB warm paper background, teal accent
report.png 138 KB white background, navy text, blue accent
reportage.png 138 KB sage #eef1ea background, teal accent
slate.png 139 KB slate #0f172a background, light text, blue accentScreenshots are saved in the author's posts/samples/research-design-system folder. The slate render was inspected visually: the stat tiles, table, side box and warning box were all legible on the dark ground.
Colour tokens each theme binds (read from the CSS)
grep -- '--c-bg\|--c-text\|--c-accent' themes/*.css
bulletin bg var(--paper) text var(--ink) accent var(--teal-deep)
report bg #fff text var(--navy) accent var(--blue)
reportage bg #eef1ea text #1d2321 accent #1f5f5b
slate bg #0f172a text #e2e8f0 accent var(--blue-web)Only the first three semantic tokens are shown; each theme binds about a dozen.
Structure of the kit
ls tokens themes components templates print docs
tokens: tokens.css tokens.json
themes: bulletin.css report.css reportage.css slate.css
components: components.css
templates: bulletin.html dashboard.html report.html
print: print.css
docs: index.htmlA clone of the repo on 19 Oct 2026.
Ways to use it
| Method | How it works |
|---|---|
| Copy a template | Start from templates/report.html, bulletin.html or dashboard.html and replace the text. |
| Link the CSS | Load tokens, theme, components and print in that order, then add class="rds theme-<name>" to body. |
| Print to PDF | print/print.css sets A4 page rules for WeasyPrint; follow the README's warnings about page-total spans and flex containers. |
| Via an AI assistant | Ask Claude Code or Gemini CLI to turn your notes into a page using the report template and theme-reportage. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Explain the research-design-system repository in plain English: what problem it solves, what the main files do, and what I need installed.
- Build a one-page report from my notes below using templates/report.html and the theme-reportage theme: [paste notes].
- Create a fifth theme called theme-sand by rebinding the --c-* tokens in themes/report.css, and show me a screenshot.
- Explain the three bugs listed in the README and show where each fix lives in components.css and print.css.
- Convert my existing HTML page to use the rds classes, keeping units in table headers and a source note under each table.
- Check my page for the rule violations in the README: raw palette values in components, missing source notes, horizontal scroll.
Limits and honest caveats
- Conceptual starter kit, not a finished brand or engineering design.
- The numbers inside the shipped templates (for example trade totals in the sample table) are placeholder example content, not data to cite.
- Only the visual render of the four themes was run; the WeasyPrint PDF path and the Blogger theme in blogger-theme/ were not tested for this post.
- A scratch copy of the report template was edited per theme for the screenshots; the repo itself was not modified.
- Dark mode is opt-in; the page will not follow the operating system unless you add data-theme="dark" yourself, which is deliberate.
Sources: research-design-system README, templates, themes and components; four theme renders made on 19 October 2026 from a fresh clone with headless Google Chrome on a scratch copy of templates/report.html; screenshots saved under ~/repo-demos/posts/samples/research-design-system. WeasyPrint was not run.
- v1.0.0 — 26 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
