Smileybones Design System from arXiv
Smileybones Design System from arXiv
These pages hold arXiv's approved patterns for front-end interfaces built around accessibility, usability, and our brand. They hold design tokens, component specs, typography, color, accessibility requirements, interactive pattern references, and more. Optimized for both human and agent digestion, the aspirational dream is that you give your agent your content, goals, and the link to the DS and say "make it so". To help us get there, share your feedback and implementation experiences so we can improve the DS together.
How to get started with the design system: basic markup, which files to link to, in what order, and a handful of things to avoid.
Hard constraints for all arXiv frontend work — internal tools and public-facing pages.
The full arXiv palette, rendered.
In the design system, every colour comes from a token and the tokens flip in each mode.
arXiv sets all text in the IBM Plex family with STIX Two Math for notation.
Every gap on arXiv pages comes from one spacing scale.
The design system uses the Lucide icon set which is open source, community supported, and available for both commercial and non-commercial use under the ISC license.
Each arXiv button family shares the same mechanical spec, with color used to differentiate by context: Open Blue for public pages and Access Lime for internal tools.
Text links are simple but important to get right.
The design system supports highly accessible forms with robust validation display options.
Alerts are a critical component of successful user journeys.
When arXiv has something special to say on the platform itself, this is how we do it.
A small rounded element used for categories, search filters, states, and other small multiples.
The arXiv public-page header sets the tone for the entire platform: simple, straightforward, and utilitarian.
The universal arXiv public-page footer (.ds-site-footer).
The bars under the site header that tell a reader where they are inside an area: secondary navigation, two levels of it, and steps.
Controls for moving through a list: one item at a time with the pager, or a group of items at a time with numbered pages.
Our primary patterns for differentiating and organizing content based on user needs.
When you need to draw a box around related content, reach for a card.
The table and what can be built on it: sortable columns, a filter toolbar, row selection and bulk actions.
A search page contains many components and elements documented elsewhere.
Options to toggle open additional content.
A window that overlays the background page until it is answered or dismissed.
Displaying paper-related content is arXiv's richest, most complex, and highest stakes design challenge.
Rules for anyone — person or agent — writing text that ships: interface copy, error messages, instructions, and the docs in this repo.
What arXiv stands for, how that differs from the rest of the research-publishing field, and what it looks like when it reaches the page.
The written color spec, and the source of truth for the colors page.
Build only from the canonical folders. Everything else in the repository is for exploring ideas, planning, or testing. AI coding agents start at AGENTS.md, which holds the same map with a reading order.
| Folder | Status | What it holds |
|---|---|---|
docs/ |
Canonical | The documentation: rules, pattern pages, and the stylesheets. |
docs/assets/ |
Canonical, for images | arXiv's official image library: logos, illustrations, backgrounds, and photos. Other repositories link to these files by URL. |
templates/ |
Canonical, for markup | The shared head, header, and footer that other arXiv apps install. Their styles come from docs/. |
verification/ |
Testing | The automated checks, audits, design reviews, and agent tests. |
whiteboard/mockups/ |
Exploration | Whole-page explorations in progress. A pattern moves into docs/ when it is stable. |
whiteboard/planning/ |
Exploration | The backlog, proposals, and decision logs. |
blog-theme/ |
Separate project | A packaged copy of the blog.arxiv.org theme, a separate project that extends the design system. |