Contribute

Setup

The documentation on this site is created and edited by a variety of contributors. If you would like to contribute to the documentation, please follow the steps below.

1. Request access to GitHub.

2. Learn about using Markdown basic syntax.

3. Create or edit any .md (or .mdx) files in src/content/docs/ directory. All files within are mapped to a filename based URL structure.

   Eg. the content at src/content/docs/start/contribute.mdx is available at /start/contribute as you can see in the current URL.

   Any documentation nested within directories will be automatically included in the sidebar navigation. For advanced use-cases you can configure sidebar in astro.config.js.

   Tip

   If you are not comfortable using git you can easily edit files directly on GitHub by clicking the ‘Edit page’ link at the bottom of each page.

   Make sure to create a Pull Request when doing this, so all changes can be team reviewed.

   

4. Additional reading for more advanced content.

   Note

   The previous steps are more than enough to make meaningful contributions to the documentation.

   However if you have a technical basis, continue with these resources to create more advanced content.

   • CommonMark Spec
   • What is MDX
   • Astro & Markdown
   • Starlight & Markdown
   • Starlight Components

CSS Layers

The styleguide is structured using CSS layers to ensure proper loading order and to avoid conflicts with both legacy and otherwise globally available styles. The layers are organized as follows:

• legacy — “legacy” current design styles
• tng
  • tng.reset
  • tng.core
  • tng.layouts
  • tng.components
  • tng.userstyles
  • tng.utilities

Components

Many components are one-on-one with an HTML element.

One Root

Each component should target one tng-* class.

.tng-tag {
  /* All styles go in here */
}

Nested elements

When your component contains additionally nested elements (with or without classes) you can target then using CSS nesting.

.tng-alert {
  header,
  .header {
    /* header styles */
  }
}

Note

We love semantic HTML. But always provide a fallback class to be used.

Nested components

Often the components will be used in a composition. You can target nested components the same way by using CSS nesting.

<div class="tng-badge">
  Toyota
  <i class="tng-icon close"></i>
</div>

.tng-badge {
  --tng-badge-border-color: var(--tng-color-border-neutral-default);

  .tng-icon {
    color: var(--tng-badge-border-color);
  }
}

• Internal variables
  • is-…
  • at-…

Utilities

Most of our utilities are built to be used specifically with our styleguide layout and components. Using them on random elements will and should not do anything.

.gap-none {
  --tng-gap: var(--tng-spacing-none);
}

All components should clearly document which utilities they support.