Skip to content

Rebranded "Roux Components" to just Roux #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pangolingo merged 4 commits into from
Jun 14, 2026
Merged

Rebranded "Roux Components" to just Roux #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
acd7fec
Rebranded "Roux Components" to just Roux
pangolingo Jun 5, 2026
ef2afdc
Copy updates:
pangolingo Jun 12, 2026
597880e
Autoformatted
pangolingo Jun 12, 2026
591fdf0
Misc fixes
pangolingo Jun 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
241 changes: 47 additions & 194 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,18 @@
# Roux
# Roux CSS & Components
Comment thread
pangolingo marked this conversation as resolved.

A boilerplate of pre-defined native CSS architecture and styling to kickstart your project. You may have used [Bitters] in the past—move on over to a fully native setup with Roux.
A boilerplate of pre-defined native CSS architecture, styling, and HTML to kickstart your project.

## See it in action

[View the docs site][docs site] to see Roux's base styling for forms, buttons, tables, and typography.

## What is Roux?

Roux gives you an organized foundation of CSS files, variables, and base styles so you can start building immediately instead of setting everything up from scratch. It's **a structured starting point for writing your own CSS**—not a framework like Tailwind or a UI library with pre-built components. Think of it like a GitHub template repo, but for your stylesheets.
Roux gives you an organized foundation of CSS files, variables, base styles, and simple HTML components so you can start building immediately instead of setting everything up from scratch. It's **a structured starting point for writing your own CSS and HTML**—not a framework like Tailwind or Material UI. Think of it like a GitHub template repo, but for your stylesheets and basic component markup.

You can cherry-pick what you need, use it for inspiration, or adopt the whole system—whatever works for your project. It's flexible and extendable, but opinionated about what matters. All HTML components aim to be accessible and semantic by default.

You can cherry-pick what you need, use it for inspiration, or adopt the whole system—whatever works for your project.
You may have used [Bitters] and [Refills] in the past—move on over to a fully native setup with Roux.

## The problem it solves

Expand All @@ -16,6 +22,7 @@ When you start a new web project, you face a blank CSS file and dozens of decisi
- Should I define colors and spacing as variables, or hardcode them?
- Do I need to reset browser defaults?
- How do I structure forms, buttons, and typography consistently?
- Is my HTML accessible?

Without a plan, you may end up with unmaintainable and disorganized CSS files that are not approachable to you or your team. Roux solves this by providing thoughtful defaults and organization patterns that scale with your project.

Expand All @@ -32,7 +39,7 @@ Without a plan, you may end up with unmaintainable and disorganized CSS files th
### Don't use Roux if you:

- Prefer utility-first frameworks like Tailwind
- Need pre-built UI components (use a component library instead)
- Need advanced JavaScript-heavy UI components
- Already have an established CSS system you're happy with

## What you get
Expand All @@ -41,10 +48,7 @@ Without a plan, you may end up with unmaintainable and disorganized CSS files th
- **CSS custom properties:** Colors, spacing, font sizes defined as variables in one place
- **Base element styling:** Sensible defaults for buttons, forms, tables, and more
- **A system to build on:** Not a finished product, but a solid foundation you customize

## See it in action

[View the demo on CodePen][codepen] to see Roux's base styling for forms, buttons, tables, and typography.
- **Baseline HTML components:** A set of basic, semantic, accessible UI components

## Installation

Expand All @@ -66,8 +70,9 @@ After installation:
1. **Customize your colors:** Open `css/base/_variables.css` and change the color values to match your project.
2. **Link the main CSS file:** Import or link to `css/app.css` in your HTML.
3. **Start building:** Add your component styles in `css/components/`.
4. **Compile (optional):** Use your preferred CSS compiler to bundle everything into one file
- This project uses [lightning CSS] to minify and compile the CSS into one file. [There are lots of options for CSS compiliation](https://www.alwaystwisted.com/articles/UnSassing-my-CSS-CSS-imports), depending on your project setup and your own preferences. If you're using [Dart Sass](https://sass-lang.com/dart-sass/), you'll need to use `@use` instead of `@import` in your main `app.css` file (you'll also need to switch your file types from `css` to `scss`).
4. **Copy components:** Grab boilerplate component HTML from the [docs site]
5. **Compile (optional):** Use your preferred CSS compiler to bundle everything into one file
- This project uses [lightning CSS] to minify and compile the CSS into one file. [There are lots of options for CSS compilation](https://www.alwaystwisted.com/articles/UnSassing-my-CSS-CSS-imports), depending on your project setup and your own preferences. If you're using [Dart Sass](https://sass-lang.com/dart-sass/), you'll need to use `@use` instead of `@import` in your main `app.css` file (you'll also need to switch your file types from `css` to `scss`).
- To compile in this repo, run `npm i` then `npm run build` (will output into a `dist` folder).

That's it! You now have an organized CSS foundation to build on.
Expand Down Expand Up @@ -114,7 +119,7 @@ css/
2. `base/_variables.css` is one of the outliers of our base files as it stores all of our [custom properties]. This comes before all of the other base files since it's a dependency. You don't have to change any of these values if you don't want to. However, you'll likely want to at least adjust the colors. **[More on variables](#variables)**
3. `base/_fonts.css` is the other outlier as files like `_typography.css` may rely on it. It's commented out for now since it needs an actual font file to work and you may want to remove it if importing a font in a different way. **[More on fonts](#fonts)**
4. The rest of the base files make use of many of the custom properties and are not dependent on each other. They're currently in ABC order. **[More on base files](#base)**
5. The `components` folder is empty. This is where you'll put your component-based styles (e.g. `components/_card.css`). Ensure the import list is in ABC order for readability.
5. The `components` folder is where you'll put your component-based styles (e.g. `components/_card.css`). Ensure the import list is in ABC order for readability.
6. Utilities are last! Right now there's only one utility. Add in any other global utilities you might have that can be applied as a class. You can prepend them with `.u-[utility-name]` and give them their own CSS file. **[More on utilities](#utilities)**

## Customization guide
Expand Down Expand Up @@ -217,34 +222,29 @@ h3 {

### Buttons

Roux uses a classname for a "button" style since it can be applied to both `button` elements and `a` elements that want to appear as a button. We've defined a few variants (primary and secondary) to work from. When applying it to an element, use both `button` and `button--{variant}`. [See the demo codepen][codepen] for structuring.
Roux uses a classname for a "button" style since it can be applied to both `button` elements and `a` elements that want to appear as a button. We've defined a few variants (primary and secondary) to work from. When applying it to an element, use both `button` and `button--{variant}`.

#### Example

[View example buttons on the docs site][docs site buttons]
Comment thread
pangolingo marked this conversation as resolved.

```html
<button type="button" class="button button--primary">A primary button</button>
<a href="#" class="button button--secondary"> A secondary button link </a>
```

### Forms

Most form styling relies on how you structure the HTML. In Roux's styling, you should be nesting an input within a label. [See the demo codepen][codepen] for structuring.
Most form styling relies on how you structure the HTML. In Roux's styling, you should be nesting an input within a label.

#### Example

[View example forms on the docs site][docs site forms]

```html
<label for="email">
<span>Your email</span>
<input
id="email"
type="email"
name="email"
autocapitalize="off"
autocorrect="off"
spellcheck="false"
required
autocomplete="email"
/>
<input id="email" type="email" name="email" />
</label>
```

Expand All @@ -270,16 +270,7 @@ If you prefer to keep those elements separate, you can adjust the CSS in the for

```html
<label for="email"> Your email </label>
<input
id="email"
type="email"
name="email"
autocapitalize="off"
autocorrect="off"
spellcheck="false"
required
autocomplete="email"
/>
<input id="email" type="email" name="email" />
```

```css
Expand Down Expand Up @@ -314,6 +305,8 @@ Any global animations can go here. Roux's only animation defines smooth scrollin

Basic styling for the `details` and `summary` elements with a custom details marker caret.

[View example disclosures on the docs site][docs site disclosures]

### Layout

`base/css/_layout.css`
Expand All @@ -340,190 +333,43 @@ Defines pictures, videos, etc. as block elements that should size responsively w

Default setup and some base styles for `dialog` elements. This includes some transition declarations as well as `::backdrop` styling.

The `.slide-in` class can be added for a smooth slide-from-bottom transition when opening a modal (and a slide out on close). [See the codepen demo][codepen] for setup in HTML and Javascript.

#### Tips

- Use the autofocus attribute on the first interactive element you want to focus to when a modal is open (usually the close modal button).
The `.slide-in` class can be added for a smooth slide-from-bottom transition when opening a modal (and a slide out on close). [See the docs site][docs site modals] for setup in HTML and Javascript.

#### Example

**Default modal**

```html
<dialog aria-modal="true">
<button class="button button--plain" type="button" autofocus>Close</button>
<p>Hello there</p>
</dialog>
```

**Slide in modal**

```html
<dialog class="slide-in" aria-modal="true">
<button class="button button--plain" type="button" autofocus>Close</button>
<p>Hello there</p>
</dialog>
```
[View example modals on the docs site][docs site modals]

@pangolingo pangolingo Jun 5, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm keeping the CSS examples in this README, but pointing to the docs site for HTML.


### Tables

`base/css/_tables.css`

Rounded border and striped row styling for tables. This also includes classes to make an overflow scroll table for data sets that are wider than the viewport. [See the codepen demo for structure][codepen].
Rounded border and striped row styling for tables. This also includes classes to make an overflow scroll table for data sets that are wider than the viewport.

#### Example

**A plain table**

```html
<table>
<caption>
Monthly spending
</caption>
<thead>
<tr>
<th>Month</th>
<th>Savings</th>
</tr>
</thead>
<tbody>
<tr>
<td>January</td>
<td>$100</td>
</tr>
<tr>
<td>February</td>
<td>$80</td>
</tr>
<tr>
<td>March</td>
<td>$30</td>
</tr>
</tbody>
<tfoot>
<tr>
<td>Sum</td>
<td>$210</td>
</tr>
</tfoot>
</table>
```

**A striped table**

```html
<table class="table--striped">
<caption>
Monthly spending
</caption>
<thead>
<tr>
<th>Month</th>
<th>Savings</th>
</tr>
</thead>
<tbody>
<tr>
<td>January</td>
<td>$100</td>
</tr>
<tr>
<td>February</td>
<td>$80</td>
</tr>
<tr>
<td>March</td>
<td>$30</td>
</tr>
</tbody>
<tfoot>
<tr>
<td>Sum</td>
<td>$210</td>
</tr>
</tfoot>
</table>
```

**A striped table with overflow scroll for smaller viewports**

```html
<div class="table-outer-wrapper">
<div class="table-inner-wrapper">
<table class="table--striped">
<caption>
Monthly spending with overflow container for smaller viewports
</caption>
<thead>
<tr>
<th>Category</th>
<th>Planned</th>
<th>Actual</th>
<th>Difference</th>
</tr>
</thead>
<tbody>
<tr>
<td>Rent/Mortgage</td>
<td>$1,200</td>
<td>$1,200</td>
<td>$0</td>
</tr>
<tr>
<td>Utilities</td>
<td>$150</td>
<td>$140</td>
<td>-$10</td>
</tr>
<tr>
<td>Groceries</td>
<td>$400</td>
<td>$420</td>
<td>+$20</td>
</tr>
<tr>
<td>Transportation</td>
<td>$100</td>
<td>$80</td>
<td>-$20</td>
</tr>
<tr>
<td>Entertainment</td>
<td>$200</td>
<td>$220</td>
<td>+$20</td>
</tr>
<tr>
<td>Miscellaneous</td>
<td>$100</td>
<td>$90</td>
<td>-$10</td>
</tr>
</tbody>
</table>
</div>
</div>
```
[View example tables on the docs site][docs site tables]

### Typography

`base/css/_typography.css`

A fairly unopinionated typographical setup. This isn't a type scale, but some basic defaults such as ensuring headings are bolded and using a pretty text wrap on `h1`s. This also leverages the base typographic custom properties in `body`. You can use the `--font-size--[variant]` custom properties in `_variables.css` to be more specific about type size.

[View example typography on the docs site][docs site typography]

### Components

This folder is empty! But this is where you'd put any component-based CSS files.
This is where you'd put any component-based CSS files. It starts with some baseline components.

#### Example

```text
components/
├── _card.css
├── _header.css
├── _navigation.css
└── _footer.css
├── _alert.css
├── _badge.css
├── _loading-indicator.css
├── _page-footer.css
└── ...
```

### Utilities
Expand Down Expand Up @@ -569,9 +415,16 @@ We are [available for hire][hire].

<!-- END /templates/footer.md -->

[docs site]: https://roux.thoughtbot.dev/
[docs site typography]: https://roux.thoughtbot.dev/component-library/typography.html
[docs site buttons]: https://roux.thoughtbot.dev/component-library/button.html
[docs site forms]: https://roux.thoughtbot.dev/component-library/form.html
[docs site disclosures]: https://roux.thoughtbot.dev/component-library/disclosure.html
[docs site modals]: https://roux.thoughtbot.dev/component-library/dialog.html
[docs site tables]: https://roux.thoughtbot.dev/component-library/table.html
[bitters]: https://github.com/thoughtbot/bitters
[refills]: https://github.com/thoughtbot/refills
[Rails setup guide]: guides/rails-setup.md
[codepen]: https://codepen.io/enatario/pen/LEppZLZ
[custom properties]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties
[lightning CSS]: https://lightningcss.dev/
[normalize]: https://github.com/necolas/normalize.css
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "roux",
"version": "0.2.2",
"description": "A boilerplate of pre-defined native CSS styling",
"description": "A boilerplate of pre-defined native CSS styling & HTML components",
"type": "module",
"homepage": "https://github.com/thoughtbot/roux",
"main": "index.js",
Expand Down
2 changes: 1 addition & 1 deletion site/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Roux Component Library Site
# Roux Docs Site

## Development

Expand Down
4 changes: 2 additions & 2 deletions site/_includes/layouts/base.njk
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{%- set siteName = 'Roux Components' -%}
{%- set siteName = 'Roux CSS & Components' -%}
{%- set siteUrl = 'https://roux.thoughtbot.dev' -%}
{%- set siteDescription = 'Extend Roux CSS with ready-to-use components to build your project.' -%}
{%- set siteDescription = 'A boilerplate of pre-defined native CSS architecture, styling, and HTML to kickstart your project.' -%}
{%- set pageTitle = title ~ ' - ' ~ siteName if title else siteName -%}
{%- set pageDescription = description or siteDescription -%}
<!DOCTYPE html>
Expand Down
2 changes: 1 addition & 1 deletion site/_includes/partials/_header.njk
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
Skip to main content
</a>

<a class="header-logo" href="{{ '/' | url }}"> Roux Components </a>
<a class="header-logo" href="{{ '/' | url }}">Roux CSS & Components</a>
<div class="header-actions">
<a href="https://github.com/thoughtbot/roux"
><img
Expand Down
Loading
Loading