Contributing

Contributing to docs

Building and maintaining a design system takes a lot of work. Some of this work is technical in scope—“simply” ensuring that code is written that does what it’s supposed to do. But much of the work in building a design system is non-technical: debating tradeoffs, defining best practices, and uncovering what patterns are uniquely suited for building this product.

Any tool can be misused, so it’s up to us to make sure that not only is the design system built well, but that it’s understood. Enter docs! A source of truth, a support tool, and a healthy record-keeping practice.

Who can contribute

Anyone who works at Scribe can add to these docs. Stylus docs are checked into our GitHub repository alongside the rest of our code, and go through the same review and merge process.

There are three main ways to contribute to the docs:

• directly contribute a change by creating a pull request (PR)
• file an issue in Linear to let us know of something wrong or missing
• participate in discussions by commenting on existing issues or pull requests, or in #design-system on Slack

How to contribute

All of the docs on this site are written in MDX. MDX lets you write Markdown alongside embedded components. This lets us display live code examples beside regular text.

If you’re a developer, you can make edits the same way you do for other features in our codebase.

1. Pull the latest changes from the colony repository.

2. Navigate to the docs package:

   cd platform/packages/stylus-docs

3. Start the Astro dev server:

   yarn dev

4. Preview changes at localhost:4321. Edits will hot reload in the browser.

If you don’t have a local dev environment, you can still make changes to the docs. You need to have a GitHub account and have access to the colonylabs organization.

Note

There’s a more streamlined setup for editing using GitHub Codespaces. This allows you to preview edits in real time, without waiting for a Vercel deployment. Codespaces is a paid feature that requires some additional setup. Stay tuned.

Writing guidelines

Write to help a reader accomplish what they came into docs to do (learn, build, verify, upgrade, evaluate, troubleshoot…) and then, as quickly as possible, get out of docs and back to their own project.

Our goal is to document how to build with Stylus and not how Stylus is built.

Style

Be clear and helpful.

• Break up walls of text.
• Use shorter sentences.
• Define acronyms and abbreviations on first usage.
• Place important information of a paragraph in the first sentence to aid in scannability.
• Avoid overuse of exclamation points.

Be sensitive to word choice.

• Avoid ableist language like crazy, cripple, and blind to.
• Avoid unnecessarily gendered language like man-hours and mankind.
• Avoid unnecessarily violent language like hang and hit.
• Avoid non-inclusive terms like blacklist, first-class, or master.

For more details, see how to write inclusive documentation and write accessible documentation.

Headings

Use headings to break up text into organized sections.

• New sections start at the <h2> level (## in Markdown). The page title is an <h1> element.
• Don’t skip heading levels.
• Keep headings short.
• Don’t end headings with punctuation (e.g. ”:”)
• For component docs, put design guidelines first, followed by developer documentation. Props and API details should come last.

Live code

Keep code examples short. Don’t include every permutation or possibility—pick one common example and then provide a link to props or source code.

Live code will display an interactive example alongside a code block without needing to write duplicate markup. Use the live keyword within triple-backtick code blocks.

```tsx live
import { Avatar } from "stylus-ui/Avatar";

export default () => (
  <Avatar>Aaron Podolny</Avatar>
);
```

Will render as:

A

import { Avatar } from "stylus-ui/Avatar";

export default () => <Avatar>Aaron Podolny</Avatar>;

Note

You must use an .mdx file for live code blocks to work. They won’t function inside regular .md files.

Code highlighting

Use line markers and line ranges to highlight code and aid scannability.

Specific lines can be highlighted individually or as ranges in triple-backtick code blocks.

```js {1, 4, 7-8}
// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"
```

Will render as:

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

You can also highlight specific words and phrases by passing in a string.

```js "given text"
function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported';
}
```

Will render as:

function demo() {
  // Mark any given text inside lines
  return "Multiple matches of the given text are supported";
}

You can also display line insertions and deletions, diff views, and other highlight styles. For details, see the Expressive Code docs.

Asides

Use a Markdown aside to call out accessibility advice, performance tips, common gotchas, and other details.

To display an aside, use the ::: block syntax with the keyword note, tip, caution, or danger.

:::note
An important aside.
:::

Will render as:

Note

An important aside.

Different keywords will display different colors and icons.

Tip

Here’s a handy pointer.

Caution

Careful.

Danger

Watch out!

You can also pass in a custom title. For details, see the Starlight docs.

Contributing to code

The code contribution process is pretty informal right now! If you see something that needs fixing, check Linear for any existing tickets and post in #design-system on Slack.