# NBS Product Design System
> Nelnet Business Solutions Product Design System - Components, design tokens, icons, and content guidelines.
---
# Welcome
## Introducing NPDS: The NBS Product Design System
## Why NPDS?
### User Experience
Our goal is to create experiences that are:
- Easy to use: Help people get things done quickly and without confusion.
- Accessible for everyone: Work for people of all abilities.
- Consistent across devices: Look and feel right on phones, tablets, and computers.
- Built around real people: Listen to users, test ideas, and improve based on their needs.
### Developer Experience
We enable developers to:
- Build faster: Use modular, reusable components that are framework-agnostic.
- Ensure performance and security: Prioritize reliability, speed, and secure coding practices.
- Onboard quickly: Access comprehensive documentation that reduces ramp-up time and promotes best practices.
- Maintain consistency and scalability: Apply shared design patterns and coding standards to minimize technical debt and ensure long-term scalability.
### Designer Experience
Designers benefit from:
- Systematic design language: Tokens and semantic structures ensure visual consistency.
- Clear visual hierarchy: Components designed to guide attention and enhance usability.
- Creative flexibility within standards: Innovate while adhering to accessibility and organizational guidelines.
## What is it?
Our system consists of the following:
- A Figma component library
- A design tokens npm package
- A web components npm package
- An icon library npm package
- Shared documentation powered by Storybook
## Resources
- [Figma Component Library](https://www.figma.com/file/g4KSDEnxR7gxIFfwpPn7I5/NPDS?type=design&node-id=3866-6951&mode=design)
- [NPDS Repository](https://github.com/nelnet-nbs/npds-lib-design-system)
- [Framework Sandbox Repository](https://github.com/nelnet-nbs/npds-lib-framework-sandbox)
## Changelogs
The NPDS packages adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Each package has its own changelog.
- [Design Tokens](https://npds.nelnet.com/llms/design-tokens-changelog-documentation.md)
- [Components](https://npds.nelnet.com/llms/components-changelog-documentation.md)
- [Icon Library](https://npds.nelnet.com/llms/icons-changelog-documentation.md)
## Development Process
Component development follows a standard process, indicated by one of the following status tags on the component documentation.
`Designed``Development``Review``Beta``Ready`
---
# Installation
There are a few steps you need to take before you can use NPDS components in your project.
## Install packages
Install the components and design tokens npm packages in your project workspace.
```
npm install @nbs/npds-components @nbs/npds-design-tokens
```
## Import styles and fonts
Import the fonts and design tokens into your global stylesheet.
```
@import url("https://fonts.googleapis.com/css2?family=Fira+Code&family=Inter:wght@400;500;600;700&display=swap");
@import "@nbs/npds-design-tokens/index.css";
```
## Configure your framework
Follow the additional [framework configuration](https://npds.nelnet.com/llms/getting-started-frameworks-documentation.md) if your project uses Angular or Vue.
## Import components
Cherry pick and import the components you want to use in your project.
```
import "@nbs/npds-components/button";
```
## Use components in templates
Once imported, custom elements can be used in templates just like native elements. Individual component documentation has additional usage information, examples, and code snippets.
```
My Button
```
---
# Frameworks
Web components can be used with any framework or none at all. However, some frameworks may need some help recognizing custom elements. If your project uses Angular or Vue, reference the guides on this page.
Additionally, check out our [Framework Sandbox](https://github.com/nelnet-nbs/npds-lib-framework-sandbox) repository for implementation examples.
## Angular
Custom elements work well with Angular. [Custom Elements Everywhere](https://custom-elements-everywhere.com/#angular) gives Angular a perfect score based on tests designed to gauge compatibility.
### Import and add the custom elements schema
Import `CUSTOM_ELEMENTS_SCHEMA` from `@angular/core` and add it to the `schemas` property on the `@NgModule` decorator. This configuration will allow Angular to recognize custom element tag names.
The following example shows these modifications applied to a basic module.
```
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core"; // Import CUSTOM_ELEMENTS_SCHEMA
import { BrowserModule } from "@angular/platform-browser";
import { AppComponent } from "./app.component";
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule],
providers: [],
bootstrap: [AppComponent],
schemas: [CUSTOM_ELEMENTS_SCHEMA], // Add CUSTOM_ELEMENTS_SCHEMA to the schemas property
})
export class AppModule {}
```
### Prepare component attributes for internationalization
When using Angular's [localize package](https://angular.dev/guide/i18n/add-package), ensure that any NPDS component attributes that need translation are properly marked using [Angular's `i18n-{attribute}` syntax](https://angular.dev/guide/i18n/prepare#mark-element-attributes-for-translations).
```
```
## Vue
Custom elements work well with Vue. [Custom Elements Everywhere](https://custom-elements-everywhere.com/#vue) gives Vue a perfect score based on tests designed to gauge compatibility.
### Instruct Vue to recognize specific tag names
Instruct Vue to treat tags names starting with `npds-` as native custom elements via the `IsCustomElement` [Vue compiler option](https://vuejs.org/api/application.html#app-config-compileroptions-iscustomelement).
```
template: {
compilerOptions: {
isCustomElement: (tag) => tag.startsWith("npds-") // Add the isCustomElement Vue compiler option
}
}
```
---
# VS Code
## Intellisense
To set up Intellisense code completion and documentation, add the following to the `.vscode/settings.json` file in your project:
```
"html.customData": [
"./node_modules/@nbs/npds-components/lib/vscode.html-custom-data.json"
]
```
It may be necessary to restart VS Code after updating your settings.
---
# Frequently Asked Questions
Find quick answers to common questions about NPDS. If you have additional questions, reach out to our team at [z-NPDS@nelnet.net](z-NPDS@nelnet.net).
## About
### What does NPDS stand for and what is it?
NPDS stands for NBS Product Design System, and it's a collection of documentation, design tokens, icons, [Figma components](https://www.figma.com/file/g4KSDEnxR7gxIFfwpPn7I5/NPDS?type=design&node-id=3866-6951&mode=design), and web components that together enable product designers and developers to improve and enhance our products.
### What are the benefits to NPDS?
- Reduced visual complexity and increased end-user accessibility will improve overall user experience.
- NPDS components can be used like native HTML elements and will allow NPDS to work in any framework or none at all.
- A single set of components that can be used with a variety of front-end stacks will bring consistency across our products and services.
- Robust centralized documentation shared by product designers and developers will help everyone use NPDS consistently.
- Integrated automatic visual testing will catch unintended changes before they can reach production.
All of this means that both product designers and developers will be able to work faster and more efficiently.
## Implementation
### What frameworks does NPDS work in?
NPDS utilizes [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) built with [Lit](https://lit.dev/). These components can be used with any framework or none at all.
- Some frameworks may need some help recognizing custom HTML elements. For more information, reference our [framework configuration](https://npds.nelnet.com/llms/getting-started-frameworks-documentation.md).
- Additionally, check out our [Framework Sandbox](https://github.com/nelnet-nbs/npds-lib-framework-sandbox) repository for implementation examples.
### Will NPDS components be affected by the existing styling in our product?
Each NPDS component is self-contained, with styling and functionality encapsulated within the shadow DOM. Design tokens exported as CSS custom properties pierce through the shadow DOM and drive the look and feel of our system.
## Adoption
### When will NPDS be production-ready?
The system is production-ready now. An initial set of components is available for you and your product designer to implement, with a full suite coming over the course of 2024.
### How do we know what components are ready and what's coming up next?
The documentation for each component has a tag next to the title that indicates the component's place in the [development process](https://npds.nelnet.com/llms/welcome-documentation#development-process.md). Additional information about upcoming work can be found in the [User Experience roadmaps in Aha](https://nbsdev.aha.io/bookmarks/epic_gantt_roadmaps/7365901186719370346/7365901275129900049).
### Should we wait until the full library of components is available to implement NPDS?
No. The components tagged as `Ready` can now be used in both greenfield development and in application updates. Adopting NPDS is not all-or-nothing and can be done a little at a time, as more components will be added throughout the year. This will lead to slightly inconsistent user experience in the short term, but ultimately will result in a more usable, accessible product for our clients.
### When do we need to start using NPDS?
Component use strategy will be driven by your team's embedded product designer. After following a few [installation steps](https://npds.nelnet.com/llms/getting-started-installation-documentation.md), each product and service team should coordinate using NPDS components between their product designer, developers, and product owner based on their existing work, priorities, and goals.
### How do we find the time to use NPDS components in our product?
There are many opportunities to start using NPDS components in your product.
- Your product designer could incorporate NPDS components when working on a new feature that is already planned for development.
- Existing elements can be slowly replaced over time when executing other planned changes.
- NPDS components can be incorporated when older sections of your codebase are refactored.
## Contribution
### Can I write or make something and "give" it to NPDS so other teams can use it?
It depends! We welcome any ideas and want to consider them individually based on use case, complexity, and how we can prioritize it with other planned work. Reach out to our team at [z-NPDS@nelnet.net](z-NPDS@nelnet.net) for more information.
---
# Content
## Guidelines for writing clear and consistent content
## Categories
- [Voice and Tone](https://npds.nelnet.com/llms/content-voice-and-tone-documentation.md)
- [Mechanics](https://npds.nelnet.com/llms/content-mechanics-documentation.md)
- [Dates, Times, and Numbers](https://npds.nelnet.com/llms/content-dates-times-and-numbers-documentation.md)
---
# Voice and Tone
## Overview
Voice is the personality behind all of our content. Tone changes our voice to fit the situation, reflecting the user's emotional state and task.
Voice and tone shape how our users interpret content, take action, and build trust within our products. Applying these principles ensures our words are useful, accessible, and purposeful.
- **Voice:** Who we are
- **Tone:** How we say it
- **Style:** What, exactly, we say
When it comes to a cohesive product experience, voice and tone are equally as important as using shared components and patterns. Voice and tone are the difference between:
## Our voice: "The Trusted Guide"
Our voice reflects our core values and character — our personality. The Trusted Guide is a reliable mentor whose speech is **clear, wise, human,** and **purposeful**. These traits work together to create an approachable and confident voice, without being casual or overly formal. Whether someone is navigating a class roster, payment plan, or lesson plan, our voice should feel **steady and helpful**.
### Traits
#### Clear
Writing clearly means users don't have to hunt through extra words to understand. Shorter is often better, but if your testing shows that more words help users succeed, choose clarity over brevity.
#### Wise
Writing with wisdom means we use words to help our users understand their tasks and help prevent errors. We help our users learn and gain confidence as they go about their tasks.
#### Human
Our writing is by humans and for humans — some of whom use machines to interact with our products. Content should work across systems, languages, cultures, and ability levels. Bring humanity into your words by:
- Using the active voice to speak directly to users
- Choosing everyday words instead of needlessly complex ones
- Opting for gender-neutral pronouns and titles
- Avoiding idioms, jargon, technical language, and company-specific jargon that might confuse or exclude
#### Purposeful
Every word should serve a purpose in guiding, instructing, or teaching. Choose words intentionally, and let user-centric principles guide your content. Delight has a purpose, too!
## Tone
Tone expresses the attitude of our writing, and it changes according to the audience, context, and emotional state.
- **Audience:** Who is reading this screen?
- **Context:** What action is our audience taking?
- **Emotional state:** How might our audience feel while using this product or feature?
## Style
Style is the mechanics of writing — grammar, word choice, and formatting. Style varies by the component, but it should always support our voice. See more information in [Mechanics](https://npds.nelnet.com/llms/content-mechanics-documentation.md).
---
# Mechanics
## Capitalization
Determine when to capitalize certain words or phrases.
### General
#### Reserve capitalization for labels, navigation, and page titles
Don't capitalize Students, Classes, Administrators, or other common nouns in content unless referring to a specific field or option. Navigation includes menus, breadcrumbs, and tabs.
### Sentence case
Only capitalize proper nouns and the first word in a phrase. Sentence case is used for the majority of our writing.
### Title case
This is a case style in which the first letter of most major words is capitalized. Use lowercase for short articles, conjunctions, or prepositions unless they're the first or last word. Reserve title case for **page titles** (H1) and **navigational elements** (like breadcrumbs, tab groups, and left nav).
#### Title case capitalization guide
| Uppercase | Lowercase |
| --- | --- |
| - First and last word - Nouns (Product, Company, Holly) - Verbs (Add, Edit) - Adjectives (Responsive) - Adverbs (Clearly, Instantly) - Pronouns (You, It) - Subordinating conjunctions (After, Before, Since) | - Articles: a, an, the - Short conjunctions: and, but, or, nor - Prepositions ( ≤ 4 letters): in, on, at, to, for, by, of, up |
## Punctuation
### Apostrophes
Plural abbreviations don't use apostrophes.
Correct:
FACTS supports over 120 scholarship granting organizations (SGOs).
Incorrect:
FACTS supports over 120 scholarship granting organizations (SGO's).
### Commas
Always include the final comma in a series of 3 or more items. Use the Oxford comma yesterday, today, and forever!
### Periods
Use only one space after a period (full stop).
### Exclamation marks
Reserve exclamation marks for truly exciting or new content! Only use 1 exclamation mark per page, maximum! Please!
### Hyphens
#### General usage
Most prefixes work without hyphens.
Correct:
- autocorrect
- cooperate
- unofficial
- preorder
- prepay
Incorrect:
- auto-correct
- co-operate
- un-official
- pre-order
- pre-pay
Add a hyphen only when needed to prevent confusion or ambiguity. Ask Copilot or check a dictionary to make sure adding a hyphen doesn’t change the meaning of your word.
- Recreating (leisure activity) vs. re-creating (making again)
- Resign (leaving a position) vs. re-sign (signing again)
#### Em dashes
- Use `Option` + `Shift` + `-` or `Alt` + `0151` to create an em dash, and always put spaces on either side of an em dash.
- Indicate abrupt or dramatic changes in a sentence with an em dash — like this. If the break happens in the middle of a sentence — like this — use em dashes on either side of the phrase.
- Use em dashes to separate phrases that contain multiple commas, like mid-sentence lists. Whenever possible, write shorter, simpler sentences to avoid overly complex punctuation.
#### Compound modifiers
A compound modifier consists of two or more words that work together to function as one adjective. Use a hyphen when a compound modifier comes before the noun it modifies.
Correct:
- multi-factor authentication
- first-year students
Incorrect:
- multi factor authentication
- first year students
Don't use a hyphen when a compound modifier follows the noun it describes.
Correct:The new features were well received.
Incorrect:The new features were well-received.
Don't use a hyphen when a compound modifier begins with **very** or an adverb ending in **-ly**.
Correct:
- very sensitive information
- recently processed payment
Incorrect:
- very-sensitive information
- recently-processed payment
## Formatting
### Emphasizing text
#### Call out key words with bold
Use bold text to draw the reader's eye to key statements or element names in your content like menu items, button labels, screen headings, and the like. Do NOT use italics or underline to emphasize text.
#### Help users read warnings correctly and NOT skim
Capitalize “NOT” in critical messages when a sentence could be misread.
Correct:
This transaction will NOT be reattempted.
Incorrect:
This transaction will not be reattempted.
### Layout and spacing
#### Use generous spacing for readability
Ensure ample space around text elements to make the content easy to read and visually appealing.
#### Leverage white space
Use white space strategically to separate sections and guide the reader's eye, preventing the layout from feeling cluttered.
#### Ancillary components have their place next to text
- Put tags, badges, expanders, and sorting and filtering functions after text (on the right side).
- Icons display on either side of text depending on the component.
### Lists
Lists draw the reader's eye and make items easier to scan.
#### Keep punctuation simple and consistent
The label on a list should end with a colon and use proper punctuation if items are complete sentences. For example:
- The line above this one ends with a colon.
- This is a full sentence, so it ends with a period.
#### Lists should be brief
Try to limit lists to 6 or fewer items. If you need more items, use subcategories or break the list into multiple lists.
#### Bullets and numbers are not the same
Use bulleted lists when the order of the items doesn't matter (for example, a list of possible payment methods). Use numbered lists where the order of items is important (for example, steps to follow in a process).
#### Consistent phrasing makes lists even easier to read
Follow a parallel structure when listing items — ideally starting each item with an imperative, action-oriented word. Our example shows a process with items in a verb-noun pattern.
Correct:
**Notify your audience:**
1. Compose message
2. Select recipients
3. Review and send
Incorrect:
**Notify your audience:**
1. Compose your message
2. Recipient selection
3. Review & sending
---
# Dates, Times, and Numbers
## Dates
Dates may be written in short, medium, or long form. Use the long form for most content and the short or medium forms for tables or areas with limited space.
### Short form
Follow the **MM/DD/YYYY** format for dates written in short form. Include a leading zero for any month or day under 10.
Correct:12/01/2026
Incorrect:12/1/26
### Medium form
Follow the **Mth DD, YYYY** format for dates written in medium form. Medium form prevents ambiguity that can be present in the short form. Months are shortened to the first 3 letters of the month name. Since the month name is present, a leading 0 is not necessary on the day.
Correct:
- Dec 1, 2026
- May 14, 2025
Incorrect:12/1/26
### Long form
Follow the **Month Day, Year** format for dates written in long form. Include a comma after the day. Do not include ordinal indicators like -st, -nd, -rd, or -th on numerals. Since the month name is present, a leading 0 is not necessary on the day.
Correct:December 1, 2026
Incorrect:December 1 2026
Incorrect:December 1st, 2026
## Times
### Clearly denote AM and PM
Use uppercase letters only to denote AM or PM; do not use periods.
Correct:8:00 AM
Incorrect:8:00 am
Incorrect:8:00 A.M.
Incorrect:8am
## Numbers
### Digits, not words
Use digits instead of whole words to reduce cognitive load.
Correct:126
Incorrect:one hundred twenty-six
### Tight hyphens
When writing ranges of numbers, use a hyphen with no spaces on either side.
Correct:100-250
Incorrect:100 - 250
### Large numbers need help
#### Commas
Include commas in numbers with 4+ digits to reduce the risk of misinterpretation and to improve readability.
Correct:118,250
Incorrect:118250
#### Write it out
In the English language, “k” means “thousands” numerically, but this shorthand isn't universal. Write the full number in digits to include the most users. Rounded numbers, exact numbers, and number ranges are all welcome.
Correct:
- over 10,000
- 51,233
- 10,000-25,000
Incorrect:
- >10,000
- 51.23k
- 10-25k
#### Put a mask on PII
Consider PII and sensitive data — use • (bullets) to hide values when appropriate. (`Alt`+`0149` or `Option`+`8`). Use 10 bullets as a baseline, or format the bullets to partially mask the value.
Correct:
- SSN ••••••••••
- Credit card number •••• •••• •••• 5571
Incorrect:
- SSN 123-45-6789
- Credit card number 1234 5678 2233 5571
---
# Forms
## Guidelines and patterns for form design and implementation
## Categories
- [Controls](https://npds.nelnet.com/llms/forms-controls-documentation.md)
- [Layout](https://npds.nelnet.com/llms/forms-layout-documentation.md)
- [Errors](https://npds.nelnet.com/llms/forms-errors-documentation.md)
---
# Form Controls
## Labels and legends
### Keep it concise
Write clear, brief labels and legends. Avoid unnecessary words or repetition; users should understand their options at a glance.
### Labels describe data, not action
Describe the information being collected from the user. If you need to give guidance, use help text. Verbs shouldn’t be present in your labels or legends.
Correct:
- Email
- Password
- First name
- Marital Status
- Signature
Incorrect:
- Enter your email address
- Enter the password
- Write your first name
- Type your spouse’s name
- Sign here
### Use sentence case
Legend and label text use sentence case. Capitalize only the first word of each line.
### Don’t use punctuation
Labels and legends should not use any punctuation.
### Don’t end with a preposition
Labels and legends should not end with prepositions.
Correct:
- Notification recipient
Incorrect:
- Send to
- Who is this for?
### No links within focusable elements
Avoid placing links inside other focusable elements like form control labels. Doing so can cause accessibility issues, unpredictable keyboard behavior, and accidental taps — especially on mobile — while breaking expected HTML semantics.
### Present options in a logical order
List options in order of relevance to the user. Depending on your content, lists may be chronological, quantitative, or familiar.
#### Chronological
Time-based options:
- Months of the year
- Days of the week
- Morning, afternoon, evening
#### Quantitative
How much, how often, or how intense something is:
- Low, medium, high
- Never, rarely, sometimes, often, always
- Strongly disagree, disagree, neutral, agree, strongly agree
#### Familiar
Intuitive, easily recognized patterns:
- Yes, no, maybe
- Not started, in progress, completed
- True, false
- Free, basic, premium
## Required fields
### Put an asterisk on it*
Mark required fields with an asterisk (*) at the end of the field label. Include a legend reading "* indicates required field" under the page title or section heading — whichever is most applicable.
### No legends for a lonely field
If there is only 1 field in a form, and it’s required, there will be no legend. Guide users with error validation text if the input is invalid or unfilled.
---
# Form Layout
## Fields
### Left-align fields in 1 column
Fields display left-aligned in a single column. Exceptions can be made for short, logically related fields like first and last name.
### Keep related fields together
Use a field set to group connected inputs (like parts of a street address). Grouped fields reduce cognitive load.
### Make field widths make sense
A zip code doesn’t need a football field. Match your field width to the expected input so forms feel clean, intentional, and easy to scan. Use layout grids to determine appropriate sizing.
## Buttons
### Left-align form buttons
Save or submit buttons are left-aligned at the bottom of the form. Buttons are always active.
---
# Form Errors
## Best practices
### Help text v. Error text
Use help text to prevent errors before they happen and error text to guide users after an error occurs.
| Attribute | Help text | Error text |
| --- | --- | --- |
| Purpose | Prevent errors | Correct errors |
| Timing | Proactive: before user interaction | Reactive: after user interaction |
| Tone | Informative, neutral | Supportive, solution-oriented |
| Visibility | Visible always, unless replaced by error text | Conditional: only after error occurs |
| Additional ways to help users | - Thoughtfully crafted labels - Adjust the field size to help users understand what to put in it - Provide additional context via the input field by using text prefixes, suffixes, and icons | - Real-time validation: Rather than waiting until the user selects “save”, validate the input as the user types. |
### Error text positively instructs the user
Start error text with a verb to guide the user to a solution. Don’t explain what's wrong; explain what action they can take to correct the error.
Correct:
- Enter a 10-digit phone number
- Enter a future date
Incorrect:
- Invalid phone number
- Answer is too short
## Display logic
If a form control has both help text and error text, the error text will display in place of the help text when the `variant` property is set to `error`.
If a form control only has error text, the error text will display when the `variant` property is set to `error`.
If a form control only has help text, the help text will always display for all variants.
---
# Design Tokens
## A shared visual foundation for designers and developers
Design tokens are individual design decisions stored as reusable variables. Instead of hard-coded values, design tokens store visual data as human-readable names. These tokens form the foundation of our system and are shared across Figma and the NPDS npm packages.
## Tiers
- **Primitive** tokens contain the raw styles that are referenced by semantic tokens. These tokens are intended for internal use only and should not be used in final designs or code.
- **Semantic** tokens have names that convey an intended usage. These tokens are referenced by component tokens and can also be used to style elements directly.
## Usage
### Code
Design tokens are exported as [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) (commonly referred to as CSS variables) and can be used to style elements via the `var()` function. These variables include the `npds` prefix to avoid potential conflicts.
```
.my-div {
color: var(--npds-semantic-color-text-on-neutral-subtle);
background-color: var(--npds-semantic-color-background-neutral-subtle);
}
```
---
# Primitive Tokens
## A collection of core tokens for internal use
> Primitive tokens are for internal use only. When styling elements, use [semantic tokens](https://npds.nelnet.com/llms/design-tokens-semantic-overview-documentation.md).
Primitive tokens contain the raw styles that are referenced by [semantic tokens](https://npds.nelnet.com/llms/design-tokens-semantic-overview-documentation.md). The same primitive token could be used to set the value of multiple semantic tokens, but should not be used in final designs or code.
## Categories
- [Color](https://npds.nelnet.com/llms/design-tokens-primitive-color-documentation.md)
- [Size](https://npds.nelnet.com/llms/design-tokens-primitive-size-documentation.md)
- [Typography](https://npds.nelnet.com/llms/design-tokens-primitive-typography-documentation.md)
---
# Primitive Color
`Ready`
> Primitive tokens are for internal use only. When styling elements, use [semantic tokens](https://npds.nelnet.com/llms/design-tokens-semantic-overview-documentation.md).
## Neutral
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.color.white | `--npds-primitive-color-white` | #ffffff |
| primitive.color.gray.50 | `--npds-primitive-color-gray-50` | #f8f8f9 |
| primitive.color.gray.100 | `--npds-primitive-color-gray-100` | #f0f1f2 |
| primitive.color.gray.200 | `--npds-primitive-color-gray-200` | #e1e2e6 |
| primitive.color.gray.300 | `--npds-primitive-color-gray-300` | #c3c7ce |
| primitive.color.gray.400 | `--npds-primitive-color-gray-400` | #a6acb6 |
| primitive.color.gray.500 | `--npds-primitive-color-gray-500` | #8a919f |
| primitive.color.gray.600 | `--npds-primitive-color-gray-600` | #6d727e |
| primitive.color.gray.700 | `--npds-primitive-color-gray-700` | #5a5f68 |
| primitive.color.gray.800 | `--npds-primitive-color-gray-800` | #43474f |
| primitive.color.gray.900 | `--npds-primitive-color-gray-900` | #2e3136 |
| primitive.color.gray.1000 | `--npds-primitive-color-gray-1000` | #1a1c1f |
## Red
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.color.red.100 | `--npds-primitive-color-red-100` | #f9eeec |
| primitive.color.red.200 | `--npds-primitive-color-red-200` | #f7dcd8 |
| primitive.color.red.300 | `--npds-primitive-color-red-300` | #f3b7ae |
| primitive.color.red.400 | `--npds-primitive-color-red-400` | #f09084 |
| primitive.color.red.500 | `--npds-primitive-color-red-500` | #eb4f4a |
| primitive.color.red.600 | `--npds-primitive-color-red-600` | #d33737 |
| primitive.color.red.700 | `--npds-primitive-color-red-700` | #ac2d2d |
| primitive.color.red.800 | `--npds-primitive-color-red-800` | #832020 |
| primitive.color.red.900 | `--npds-primitive-color-red-900` | #5c1615 |
| primitive.color.red.1000 | `--npds-primitive-color-red-1000` | #33100b |
## Yellow
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.color.yellow.100 | `--npds-primitive-color-yellow-100` | #fef9c3 |
| primitive.color.yellow.200 | `--npds-primitive-color-yellow-200` | #fef08a |
| primitive.color.yellow.300 | `--npds-primitive-color-yellow-300` | #fde047 |
| primitive.color.yellow.400 | `--npds-primitive-color-yellow-400` | #facc15 |
| primitive.color.yellow.500 | `--npds-primitive-color-yellow-500` | #eab308 |
| primitive.color.yellow.600 | `--npds-primitive-color-yellow-600` | #ca8a04 |
| primitive.color.yellow.700 | `--npds-primitive-color-yellow-700` | #a16207 |
| primitive.color.yellow.800 | `--npds-primitive-color-yellow-800` | #854d0e |
| primitive.color.yellow.900 | `--npds-primitive-color-yellow-900` | #713f12 |
| primitive.color.yellow.1000 | `--npds-primitive-color-yellow-1000` | #422006 |
## Green
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.color.green.100 | `--npds-primitive-color-green-100` | #e3fff0 |
| primitive.color.green.200 | `--npds-primitive-color-green-200` | #c1edd3 |
| primitive.color.green.300 | `--npds-primitive-color-green-300` | #7cd7ae |
| primitive.color.green.400 | `--npds-primitive-color-green-400` | #00c388 |
| primitive.color.green.500 | `--npds-primitive-color-green-500` | #01a572 |
| primitive.color.green.600 | `--npds-primitive-color-green-600` | #0d8259 |
| primitive.color.green.700 | `--npds-primitive-color-green-700` | #1e6b4d |
| primitive.color.green.800 | `--npds-primitive-color-green-800` | #015237 |
| primitive.color.green.900 | `--npds-primitive-color-green-900` | #033825 |
| primitive.color.green.1000 | `--npds-primitive-color-green-1000` | #052015 |
## Blue
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.color.blue.100 | `--npds-primitive-color-blue-100` | #e6f3fb |
| primitive.color.blue.200 | `--npds-primitive-color-blue-200` | #cae7fa |
| primitive.color.blue.300 | `--npds-primitive-color-blue-300` | #87d0fc |
| primitive.color.blue.400 | `--npds-primitive-color-blue-400` | #54b5e7 |
| primitive.color.blue.500 | `--npds-primitive-color-blue-500` | #189dd2 |
| primitive.color.blue.600 | `--npds-primitive-color-blue-600` | #037aa7 |
| primitive.color.blue.700 | `--npds-primitive-color-blue-700` | #056488 |
| primitive.color.blue.800 | `--npds-primitive-color-blue-800` | #074d69 |
| primitive.color.blue.900 | `--npds-primitive-color-blue-900` | #063549 |
| primitive.color.blue.1000 | `--npds-primitive-color-blue-1000` | #061e2a |
## Purple
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.color.purple.100 | `--npds-primitive-color-purple-100` | #f7eef9 |
| primitive.color.purple.200 | `--npds-primitive-color-purple-200` | #f0dcf5 |
| primitive.color.purple.300 | `--npds-primitive-color-purple-300` | #e3b8f1 |
| primitive.color.purple.400 | `--npds-primitive-color-purple-400` | #d593ec |
| primitive.color.purple.500 | `--npds-primitive-color-purple-500` | #c56de5 |
| primitive.color.purple.600 | `--npds-primitive-color-purple-600` | #ad38d9 |
| primitive.color.purple.700 | `--npds-primitive-color-purple-700` | #9332b8 |
| primitive.color.purple.800 | `--npds-primitive-color-purple-800` | #6e238a |
| primitive.color.purple.900 | `--npds-primitive-color-purple-900` | #4d1861 |
| primitive.color.purple.1000 | `--npds-primitive-color-purple-1000` | #2d0e38 |
## Alpha
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.color.alpha.50 | `--npds-primitive-color-alpha-50` | #1a1c1f08 |
| primitive.color.alpha.100 | `--npds-primitive-color-alpha-100` | #1a1c1f0d |
| primitive.color.alpha.200 | `--npds-primitive-color-alpha-200` | #1a1c1f1a |
| primitive.color.alpha.300 | `--npds-primitive-color-alpha-300` | #1a1c1f26 |
| primitive.color.alpha.400 | `--npds-primitive-color-alpha-400` | #1a1c1f33 |
| primitive.color.alpha.500 | `--npds-primitive-color-alpha-500` | #1a1c1f40 |
| primitive.color.alpha.600 | `--npds-primitive-color-alpha-600` | #1a1c1f4d |
| primitive.color.alpha.700 | `--npds-primitive-color-alpha-700` | #1a1c1f59 |
| primitive.color.alpha.800 | `--npds-primitive-color-alpha-800` | #1a1c1f66 |
| primitive.color.alpha.900 | `--npds-primitive-color-alpha-900` | #1a1c1f73 |
| primitive.color.alpha.1000 | `--npds-primitive-color-alpha-1000` | #1a1c1f80 |
---
# Primitive Size
`Ready`
> Primitive tokens are for internal use only. When styling elements, use [semantic tokens](https://npds.nelnet.com/llms/design-tokens-semantic-overview-documentation.md).
The NBS Product Design System utilizes an 8 pixel grid system for size and space tokens. The 8 pixel grid system is a highly effective tool in UX design, offering numerous benefits.
- It provides a consistent framework that helps maintain visual harmony across different screen sizes and resolutions.
- By using multiples of eight for layout dimensions, padding, and margins, designers can ensure scalability and a clean aesthetic.
- It supports responsive design by fitting well with the majority of popular screen sizes, which are divisible by eight, ensuring that designs look good on any device.
These primitive tokens are used to define the semantic [size](https://npds.nelnet.com/llms/design-tokens-semantic-size-documentation.md) and [space](https://npds.nelnet.com/llms/design-tokens-semantic-space-documentation.md) tokens.
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.size.0 | `--npds-primitive-size-0` | 0px |
| primitive.size.1 | `--npds-primitive-size-1` | 1px |
| primitive.size.2 | `--npds-primitive-size-2` | 2px |
| primitive.size.4 | `--npds-primitive-size-4` | 4px |
| primitive.size.6 | `--npds-primitive-size-6` | 6px |
| primitive.size.8 | `--npds-primitive-size-8` | 8px |
| primitive.size.12 | `--npds-primitive-size-12` | 12px |
| primitive.size.16 | `--npds-primitive-size-16` | 16px |
| primitive.size.20 | `--npds-primitive-size-20` | 20px |
| primitive.size.24 | `--npds-primitive-size-24` | 24px |
| primitive.size.28 | `--npds-primitive-size-28` | 28px |
| primitive.size.32 | `--npds-primitive-size-32` | 32px |
| primitive.size.36 | `--npds-primitive-size-36` | 36px |
| primitive.size.40 | `--npds-primitive-size-40` | 40px |
| primitive.size.48 | `--npds-primitive-size-48` | 48px |
| primitive.size.56 | `--npds-primitive-size-56` | 56px |
| primitive.size.64 | `--npds-primitive-size-64` | 64px |
| primitive.size.72 | `--npds-primitive-size-72` | 72px |
| primitive.size.80 | `--npds-primitive-size-80` | 80px |
---
# Primitive Typography
`Ready`
> Primitive tokens are for internal use only. When styling elements, use [semantic tokens](https://npds.nelnet.com/llms/design-tokens-semantic-overview-documentation.md).
## Font Family
The primary typeface for the NBS Product Design System is [Inter](https://rsms.me/inter/), a typeface carefully crafted & designed for computer screens.
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.font.family.sans-serif | `--npds-primitive-font-family-sans-serif` | Inter, Arial, sans-serif |
| primitive.font.family.monospace | `--npds-primitive-font-family-monospace` | 'Fira Code', monospace |
## Size
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.font.size.11 | `--npds-primitive-font-size-11` | 11px |
| primitive.font.size.12 | `--npds-primitive-font-size-12` | 12px |
| primitive.font.size.14 | `--npds-primitive-font-size-14` | 14px |
| primitive.font.size.16 | `--npds-primitive-font-size-16` | 16px |
| primitive.font.size.20 | `--npds-primitive-font-size-20` | 20px |
| primitive.font.size.24 | `--npds-primitive-font-size-24` | 24px |
| primitive.font.size.28 | `--npds-primitive-font-size-28` | 28px |
| primitive.font.size.32 | `--npds-primitive-font-size-32` | 32px |
| primitive.font.size.40 | `--npds-primitive-font-size-40` | 40px |
## Weight
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.font.weight.400 | `--npds-primitive-font-weight-400` | 400 |
| primitive.font.weight.500 | `--npds-primitive-font-weight-500` | 500 |
| primitive.font.weight.600 | `--npds-primitive-font-weight-600` | 600 |
| primitive.font.weight.700 | `--npds-primitive-font-weight-700` | 700 |
## Line Height
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| primitive.font.line-height.12 | `--npds-primitive-font-line-height-12` | 12px |
| primitive.font.line-height.16 | `--npds-primitive-font-line-height-16` | 16px |
| primitive.font.line-height.20 | `--npds-primitive-font-line-height-20` | 20px |
| primitive.font.line-height.24 | `--npds-primitive-font-line-height-24` | 24px |
| primitive.font.line-height.32 | `--npds-primitive-font-line-height-32` | 32px |
| primitive.font.line-height.40 | `--npds-primitive-font-line-height-40` | 40px |
| primitive.font.line-height.48 | `--npds-primitive-font-line-height-48` | 48px |
| primitive.font.line-height.56 | `--npds-primitive-font-line-height-56` | 56px |
---
# Semantic Tokens
## A collection of tokens for public use
Semantic tokens have names that convey an intended usage. These tokens have values derived from [primitive tokens](https://npds.nelnet.com/llms/design-tokens-primitive-overview-documentation.md) and are referenced by component tokens. Semantic tokens can also be used to style elements directly.
## Categories
- [Color](https://npds.nelnet.com/llms/design-tokens-semantic-color-documentation.md)
- [Elevation](https://npds.nelnet.com/llms/design-tokens-semantic-elevation-documentation.md)
- [Radius](https://npds.nelnet.com/llms/design-tokens-semantic-radius-documentation.md)
- [Size](https://npds.nelnet.com/llms/design-tokens-semantic-size-documentation.md)
- [Space](https://npds.nelnet.com/llms/design-tokens-semantic-space-documentation.md)
- [Typography](https://npds.nelnet.com/llms/design-tokens-semantic-typography-documentation.md)
---
# Semantic Color
`Ready`
## Background
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.color.background.surface | `--npds-semantic-color-background-surface` | #ffffff |
| semantic.color.background.surface-alt | `--npds-semantic-color-background-surface-alt` | #f8f8f9 |
| semantic.color.background.fill | `--npds-semantic-color-background-fill` | #ffffff |
| semantic.color.background.fill-disabled | `--npds-semantic-color-background-fill-disabled` | #f0f1f2 |
| semantic.color.background.scrim | `--npds-semantic-color-background-scrim` | #1a1c1f80 |
| semantic.color.background.brand | `--npds-semantic-color-background-brand` | #037aa7 |
| semantic.color.background.neutral-bold | `--npds-semantic-color-background-neutral-bold` | #2e3136 |
| semantic.color.background.neutral | `--npds-semantic-color-background-neutral` | #6d727e |
| semantic.color.background.neutral-subtle | `--npds-semantic-color-background-neutral-subtle` | #e1e2e6 |
| semantic.color.background.informative | `--npds-semantic-color-background-informative` | #037aa7 |
| semantic.color.background.informative-subtle | `--npds-semantic-color-background-informative-subtle` | #cae7fa |
| semantic.color.background.positive-bold | `--npds-semantic-color-background-positive-bold` | #1e6b4d |
| semantic.color.background.positive | `--npds-semantic-color-background-positive` | #0d8259 |
| semantic.color.background.positive-subtle | `--npds-semantic-color-background-positive-subtle` | #c1edd3 |
| semantic.color.background.notice | `--npds-semantic-color-background-notice` | #ca8a04 |
| semantic.color.background.notice-subtle | `--npds-semantic-color-background-notice-subtle` | #fef08a |
| semantic.color.background.negative-bold | `--npds-semantic-color-background-negative-bold` | #ac2d2d |
| semantic.color.background.negative | `--npds-semantic-color-background-negative` | #d33737 |
| semantic.color.background.negative-subtle | `--npds-semantic-color-background-negative-subtle` | #f7dcd8 |
## Border
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.color.border.neutral | `--npds-semantic-color-border-neutral` | #c3c7ce |
| semantic.color.border.neutral-hover | `--npds-semantic-color-border-neutral-hover` | #a6acb6 |
| semantic.color.border.neutral-bold | `--npds-semantic-color-border-neutral-bold` | #8a919f |
| semantic.color.border.neutral-bold-hover | `--npds-semantic-color-border-neutral-bold-hover` | #6d727e |
| semantic.color.border.positive | `--npds-semantic-color-border-positive` | #0d8259 |
| semantic.color.border.negative | `--npds-semantic-color-border-negative` | #d33737 |
| semantic.color.border.negative-hover | `--npds-semantic-color-border-negative-hover` | #ac2d2d |
| semantic.color.border.disabled | `--npds-semantic-color-border-disabled` | #e1e2e6 |
| semantic.color.border.focus | `--npds-semantic-color-border-focus` | #037aa7 |
## Foreground
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.color.foreground.primary | `--npds-semantic-color-foreground-primary` | #2e3136 |
| semantic.color.foreground.secondary | `--npds-semantic-color-foreground-secondary` | #5a5f68 |
| semantic.color.foreground.tertiary | `--npds-semantic-color-foreground-tertiary` | #6d727e |
| semantic.color.foreground.disabled | `--npds-semantic-color-foreground-disabled` | #e1e2e6 |
| semantic.color.foreground.brand | `--npds-semantic-color-foreground-brand` | #037aa7 |
| semantic.color.foreground.brand-hover | `--npds-semantic-color-foreground-brand-hover` | #056488 |
| semantic.color.foreground.brand-disabled | `--npds-semantic-color-foreground-brand-disabled` | #cae7fa |
| semantic.color.foreground.on-brand | `--npds-semantic-color-foreground-on-brand` | #ffffff |
| semantic.color.foreground.neutral | `--npds-semantic-color-foreground-neutral` | #6d727e |
| semantic.color.foreground.neutral-subtle | `--npds-semantic-color-foreground-neutral-subtle` | #8a919f |
| semantic.color.foreground.on-neutral | `--npds-semantic-color-foreground-on-neutral` | #ffffff |
| semantic.color.foreground.on-neutral-subtle | `--npds-semantic-color-foreground-on-neutral-subtle` | #5a5f68 |
| semantic.color.foreground.informative | `--npds-semantic-color-foreground-informative` | #037aa7 |
| semantic.color.foreground.informative-subtle | `--npds-semantic-color-foreground-informative-subtle` | #189dd2 |
| semantic.color.foreground.on-informative | `--npds-semantic-color-foreground-on-informative` | #ffffff |
| semantic.color.foreground.on-informative-subtle | `--npds-semantic-color-foreground-on-informative-subtle` | #056488 |
| semantic.color.foreground.positive | `--npds-semantic-color-foreground-positive` | #0d8259 |
| semantic.color.foreground.positive-subtle | `--npds-semantic-color-foreground-positive-subtle` | #01a572 |
| semantic.color.foreground.on-positive | `--npds-semantic-color-foreground-on-positive` | #ffffff |
| semantic.color.foreground.on-positive-subtle | `--npds-semantic-color-foreground-on-positive-subtle` | #1e6b4d |
| semantic.color.foreground.notice | `--npds-semantic-color-foreground-notice` | #ca8a04 |
| semantic.color.foreground.notice-subtle | `--npds-semantic-color-foreground-notice-subtle` | #eab308 |
| semantic.color.foreground.on-notice | `--npds-semantic-color-foreground-on-notice` | #ffffff |
| semantic.color.foreground.on-notice-subtle | `--npds-semantic-color-foreground-on-notice-subtle` | #854d0e |
| semantic.color.foreground.negative | `--npds-semantic-color-foreground-negative` | #d33737 |
| semantic.color.foreground.negative-hover | `--npds-semantic-color-foreground-negative-hover` | #ac2d2d |
| semantic.color.foreground.negative-disabled | `--npds-semantic-color-foreground-negative-disabled` | #f7dcd8 |
| semantic.color.foreground.negative-subtle | `--npds-semantic-color-foreground-negative-subtle` | #eb4f4a |
| semantic.color.foreground.on-negative | `--npds-semantic-color-foreground-on-negative` | #ffffff |
| semantic.color.foreground.on-negative-subtle | `--npds-semantic-color-foreground-on-negative-subtle` | #ac2d2d |
## Text
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.color.text.primary | `--npds-semantic-color-text-primary` | #2e3136 |
| semantic.color.text.secondary | `--npds-semantic-color-text-secondary` | #5a5f68 |
| semantic.color.text.tertiary | `--npds-semantic-color-text-tertiary` | #6d727e |
| semantic.color.text.brand | `--npds-semantic-color-text-brand` | #037aa7 |
| semantic.color.text.on-brand | `--npds-semantic-color-text-on-brand` | #ffffff |
| semantic.color.text.link | `--npds-semantic-color-text-link` | #037aa7 |
| semantic.color.text.on-neutral | `--npds-semantic-color-text-on-neutral` | #ffffff |
| semantic.color.text.on-neutral-subtle | `--npds-semantic-color-text-on-neutral-subtle` | #5a5f68 |
| semantic.color.text.informative | `--npds-semantic-color-text-informative` | #037aa7 |
| semantic.color.text.on-informative | `--npds-semantic-color-text-on-informative` | #ffffff |
| semantic.color.text.on-informative-subtle | `--npds-semantic-color-text-on-informative-subtle` | #056488 |
| semantic.color.text.positive | `--npds-semantic-color-text-positive` | #0d8259 |
| semantic.color.text.on-positive | `--npds-semantic-color-text-on-positive` | #ffffff |
| semantic.color.text.on-positive-subtle | `--npds-semantic-color-text-on-positive-subtle` | #1e6b4d |
| semantic.color.text.notice | `--npds-semantic-color-text-notice` | #a16207 |
| semantic.color.text.on-notice | `--npds-semantic-color-text-on-notice` | #ffffff |
| semantic.color.text.on-notice-subtle | `--npds-semantic-color-text-on-notice-subtle` | #854d0e |
| semantic.color.text.negative | `--npds-semantic-color-text-negative` | #d33737 |
| semantic.color.text.on-negative | `--npds-semantic-color-text-on-negative` | #ffffff |
| semantic.color.text.on-negative-subtle | `--npds-semantic-color-text-on-negative-subtle` | #ac2d2d |
## Utility
### Background
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.color.utility.background.red | `--npds-semantic-color-utility-background-red` | #f3b7ae |
| semantic.color.utility.background.yellow | `--npds-semantic-color-utility-background-yellow` | #fde047 |
| semantic.color.utility.background.green | `--npds-semantic-color-utility-background-green` | #7cd7ae |
| semantic.color.utility.background.blue | `--npds-semantic-color-utility-background-blue` | #87d0fc |
| semantic.color.utility.background.purple | `--npds-semantic-color-utility-background-purple` | #e3b8f1 |
### Foreground
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.color.utility.foreground.red | `--npds-semantic-color-utility-foreground-red` | #5c1615 |
| semantic.color.utility.foreground.yellow | `--npds-semantic-color-utility-foreground-yellow` | #713f12 |
| semantic.color.utility.foreground.green | `--npds-semantic-color-utility-foreground-green` | #033825 |
| semantic.color.utility.foreground.blue | `--npds-semantic-color-utility-foreground-blue` | #063549 |
| semantic.color.utility.foreground.purple | `--npds-semantic-color-utility-foreground-purple` | #4d1861 |
### Text
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.color.utility.text.red | `--npds-semantic-color-utility-text-red` | #5c1615 |
| semantic.color.utility.text.yellow | `--npds-semantic-color-utility-text-yellow` | #713f12 |
| semantic.color.utility.text.green | `--npds-semantic-color-utility-text-green` | #033825 |
| semantic.color.utility.text.blue | `--npds-semantic-color-utility-text-blue` | #063549 |
| semantic.color.utility.text.purple | `--npds-semantic-color-utility-text-purple` | #4d1861 |
---
# Semantic Elevation
`Beta`
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.elevation.md | `--npds-semantic-elevation-md` | 0px 2px 12px 1px #1a1c1f26 |
| semantic.elevation.lg | `--npds-semantic-elevation-lg` | 0px 4px 24px 4px #1a1c1f1a |
---
# Semantic Radius
`Ready`
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.radius.none | `--npds-semantic-radius-none` | 0px |
| semantic.radius.sm | `--npds-semantic-radius-sm` | 4px |
| semantic.radius.md | `--npds-semantic-radius-md` | 8px |
| semantic.radius.lg | `--npds-semantic-radius-lg` | 16px |
| semantic.radius.full | `--npds-semantic-radius-full` | 999px |
---
# Semantic Size
`Development`
| Name | CSS Custom Property | Value |
| --- | --- | --- |
---
# Semantic Space
`Ready`
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.space.none | `--npds-semantic-space-none` | 0px |
| semantic.space.xxs | `--npds-semantic-space-xxs` | 2px |
| semantic.space.xs | `--npds-semantic-space-xs` | 4px |
| semantic.space.sm | `--npds-semantic-space-sm` | 6px |
| semantic.space.md | `--npds-semantic-space-md` | 8px |
| semantic.space.lg | `--npds-semantic-space-lg` | 12px |
| semantic.space.xl | `--npds-semantic-space-xl` | 16px |
| semantic.space.xxl | `--npds-semantic-space-xxl` | 24px |
---
# Semantic Typography
`Ready`
## Font Family
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.font.family.base | `--npds-semantic-font-family-base` | Inter, Arial, sans-serif |
| semantic.font.family.code | `--npds-semantic-font-family-code` | 'Fira Code', monospace |
## Size
### Body
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.font.size.body.xs | `--npds-semantic-font-size-body-xs` | 11px |
| semantic.font.size.body.sm | `--npds-semantic-font-size-body-sm` | 12px |
| semantic.font.size.body.md | `--npds-semantic-font-size-body-md` | 14px |
| semantic.font.size.body.lg | `--npds-semantic-font-size-body-lg` | 16px |
### Heading
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.font.size.heading.xs | `--npds-semantic-font-size-heading-xs` | 14px |
| semantic.font.size.heading.sm | `--npds-semantic-font-size-heading-sm` | 16px |
| semantic.font.size.heading.md | `--npds-semantic-font-size-heading-md` | 20px |
| semantic.font.size.heading.lg | `--npds-semantic-font-size-heading-lg` | 24px |
| semantic.font.size.heading.xl | `--npds-semantic-font-size-heading-xl` | 28px |
| semantic.font.size.heading.xxl | `--npds-semantic-font-size-heading-xxl` | 32px |
## Weight
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.font.weight.regular | `--npds-semantic-font-weight-regular` | 400 |
| semantic.font.weight.medium | `--npds-semantic-font-weight-medium` | 500 |
| semantic.font.weight.semibold | `--npds-semantic-font-weight-semibold` | 600 |
| semantic.font.weight.bold | `--npds-semantic-font-weight-bold` | 700 |
## Line Height
### Body
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.font.line-height.body.xs | `--npds-semantic-font-line-height-body-xs` | 12px |
| semantic.font.line-height.body.sm | `--npds-semantic-font-line-height-body-sm` | 16px |
| semantic.font.line-height.body.md | `--npds-semantic-font-line-height-body-md` | 20px |
| semantic.font.line-height.body.lg | `--npds-semantic-font-line-height-body-lg` | 24px |
### Heading
| Name | CSS Custom Property | Value |
| --- | --- | --- | --- |
| semantic.font.line-height.heading.xs | `--npds-semantic-font-line-height-heading-xs` | 20px |
| semantic.font.line-height.heading.sm | `--npds-semantic-font-line-height-heading-sm` | 24px |
| semantic.font.line-height.heading.md | `--npds-semantic-font-line-height-heading-md` | 24px |
| semantic.font.line-height.heading.lg | `--npds-semantic-font-line-height-heading-lg` | 32px |
| semantic.font.line-height.heading.xl | `--npds-semantic-font-line-height-heading-xl` | 40px |
| semantic.font.line-height.heading.xxl | `--npds-semantic-font-line-height-heading-xxl` | 48px |
---
# Design Tokens Changelog
The NPDS Design Tokens package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## 1.0.1
### Bug Fixes
- **color:** updated various primitive color tokens to support AA contrast ratio
## 1.0.0
- bumped version number to allow auto updates across organization
## 0.7.0
### Features
- **color:** added new `semantic.color.border.neutral-bold`, `semantic.color.border.neutral-bold-hover`, and `semantic.color.border.disabled` tokens
### Styles
- **color:** updated `semantic.color.border.neutral-hover` token primitive reference
## 0.6.1
### Build System
- updated `build` in `package.json` scripts to account for node 22 changes
## 0.6.0
### Features
- **color:** added new semantic scrim background color imported from Figma
## 0.5.1
### Code Refactoring
- moved `ts-node` package to top level of monorepo
## 0.5.0
### Features
- **color:** added new semantic utility color tokens imported from Figma
- **color:** added new `semantic.color.background.surface`, `semantic.color.background.surface-alt`,`semantic.color.border.negative-hover`, `semantic.color.foreground.disabled`, `semantic.color.foreground.brand-hover`, `semantic.color.foreground.brand-disabled`, `semantic.color.foreground.neutral`, `semantic.color.foreground.negative-hover`, and `semantic.color.foreground.negative-disabled` tokens
## 0.4.0
### Features
- **color:** added new primitive alpha color tokens imported from Figma
### Code Refactoring
- **elevation:** updated semantic elevation tokens to use primitive alpha color tokens
### Build System
- updated `style-dictionary` to 4.3.3 and replaced `color/css` transformer with updated `color/hex` transformer
## 0.3.1
### Build System
- removed some Style Dictionary config that didn't actually do anything
## 0.3.0
### Features
- **color:** added new semantic tokens imported from Figma
- **space:** added new `none` semantic token imported from Figma
- **button:** added new component level color tokens imported from Figma
### Bug Fixes
- updated published token names in internally used `index.json` manifest to align with Figma variable naming conventions
### Documentation
- **color, radius, space, typography:** changed status to 'Ready'
### Code Refactoring
- changed internally used `cssVariable` property name in `index.json` manifest to `cssCustomProperty`
## 0.2.0
### Features
- **elevation:** added new semantic composite tokens that match Figma styles
- **radius:** added new semantic tokens imported from Figma
- **size:** added new `0` and `1` primitive size tokens imported from Figma
### Code Refactoring
- removed unused `compilerOptions` from tsconfig file
### Build System
- updated `style-dictionary` to 4.1.3 and addressed all breaking changes
- removed `style-dictionary-utils` package, the needed functionality now exists natively within `style-dictionary`
## 0.1.1
### Bug Fixes
- excluded `README.md` and `CHANGELOG.md` from `pathFilters` in `version.json` to avoid bumping the version number when only those files are changed
### Miscellaneous Chores
- **size:** replaced existing primitive tokens with renamed ones imported from Figma
- **space:** replaced existing semantic tokens with renamed imported from Figma
### Code Refactoring
- changed css custom property selector from `body` to `:root`
## 0.1.0
### Miscellaneous Chores
- **font:** replaced existing manually entered `size`, `weight`, and `lineHeight` tokens with those imported from Figma
### Documentation
- added CHANGELOG
### Code Refactoring
- **font:** changed prefix of tokens from `text` to `font`
- **font:** changed source file names from `typography` to `font` to match prefix
- **font:** updated primitive `size` and `lineHeight` tokens to use pixel values as names instead of an abstract numerical scale
---
# Icon Library
`Ready`
The NPDS Icon Library is a curated collection of Font Awesome glyphs that helps take the guesswork out of selecting an icon for a given purpose. Consistent icon usage can help reduce cognitive load and establish familiarity across workflows and applications.
This library exists as an npm package that is installed as a dependency of the components package. It can also be upgraded indepenently of the components package to ensure that the latest icons are always available to use.
## Usage
Icons are from this library are displayed using the [Icon](https://npds.nelnet.com/llms/components-icon-documentation.md) component.
```
import "@nbs/npds-components/icon";
```
## Glyphs
| Glyph Name | Purpose | Since |
| --- | --- | --- |
| `arrow-down` | move down, sorted descending | 1.0.0 |
| `arrow-down-a-z` | sort, table, alphabetical, sorted A to Z | 1.0.0 |
| `arrow-down-from-line` | move down | 2.1.0 |
| `arrow-left` | move left | 1.0.0 |
| `arrow-left-from-line` | previous, left, move | 2.0.0 |
| `arrow-progress` | progress, path, route, flow | 3.0.0 |
| `arrow-right` | move right | 1.0.0 |
| `arrow-right-from-bracket` | check out, log out, move out | 2.0.0 |
| `arrow-right-from-line` | next, right, move | 2.0.0 |
| `arrow-right-to-bracket` | check in, move in, log in | 2.0.0 |
| `arrow-up` | move up, sorted ascending | 1.0.0 |
| `arrow-up-a-z` | sort, table, alphabetical, reverse, sorted Z to A | 1.0.0 |
| `arrow-up-arrow-down` | sort up or down, unsorted | 2.0.0 |
| `arrow-up-from-line` | move up | 2.1.0 |
| `arrow-up-right` | open in new window, link, external | 3.0.0 |
| `arrows-rotate` | refresh, reload, reset | 1.0.0 |
| `badge-check` | verify, guarantee | 2.0.0 |
| `bars` | hamburger, menu | 1.0.0 |
| `bell` | notice, notification, alert, ring | 1.0.0 |
| `bold` | bold, formatting, font, styling, wysiwyg | 2.1.0 |
| `book` | lesson plan, book | 1.0.0 |
| `bookmark` | save | 1.0.0 |
| `books` | academics, lessons, resources | 1.0.0 |
| `box-archive` | archive, files, box, document, storage | 3.0.0 |
| `briefcase` | staff, sponsor services | 1.0.0 |
| `briefcase-medical` | medical, health, health information | 1.0.0 |
| `building` | tenant, unit, business unit, single tenant, reference | 1.0.0 |
| `building-columns` | finance, international payment, bank, financial institution, ACH | 2.0.0 |
| `buildings` | tenants, units, business units, multiple tenants, reference | 1.0.0 |
| `bullhorn` | announce, announcement | 1.0.0 |
| `calendar` | date, appointment | 1.0.0 |
| `calendar-check` | date, attendance, successful date, confirmed date, scheduled, appointment | 1.0.0 |
| `calendar-xmark` | date, absent, failed date, canceled appointment | 1.0.0 |
| `camera` | photo, image, picture, capture | 1.0.0 |
| `car-side` | auto, pickup, pick up, transportation, car, driver | 2.0.0 |
| `cart-shopping` | shopping cart, shop, commerce | 1.0.0 |
| `cash-register` | cash drawer | 1.0.0 |
| `chart-line-up` | report, analytics | 1.0.0 |
| `check` | success, check | 1.0.0 |
| `chevron-down` | menu, menu below this control, expand | 1.0.0 |
| `chevron-left` | menu, menu to the left of this control, previous | 1.0.0 |
| `chevron-right` | menu, menu to the right of this control, next | 1.0.0 |
| `chevron-up` | menu, menu above this control, collapse | 1.0.0 |
| `chevrons-down` | menus | 1.0.0 |
| `chevrons-left` | menus, first, page | 1.0.0 |
| `chevrons-right` | menus, last, page | 1.0.0 |
| `chevrons-up` | menus | 1.0.0 |
| `children` | childcare, children | 1.2.0 |
| `circle-check` | success | 1.0.0 |
| `circle-dollar` | pricing, fees, cost | 1.0.0 |
| `circle-exclamation` | warning, alert | 1.0.0 |
| `circle-info` | information | 1.0.0 |
| `circle-minus` | remove, unassign | 1.0.0 |
| `circle-plus` | add, assign | 1.0.0 |
| `circle-question` | help, aid, information | 1.2.0 |
| `circle-star` | favorite, activity | 1.0.0 |
| `circle-stop` | stop | 1.0.0 |
| `circle-user` | user, avatar | 1.0.0 |
| `circle-xmark` | close (alternate) | 1.0.0 |
| `clipboard` | copy, paste | 1.0.0 |
| `clock` | time, scheduling | 1.0.0 |
| `cloud` | storage, cloud | 1.0.0 |
| `compress` | exit full screen | 3.0.0 |
| `copy` | copy, paste | 1.0.0 |
| `credit-card` | payment, processing, manage payments, credit, card, method | 1.0.0 |
| `delete-left` | back, backspace, delete (alternate) | 3.1.0 |
| `desktop` | computer, desktop | 1.0.0 |
| `dollar-sign` | currency, USD | 1.0.0 |
| `download` | download | 1.0.0 |
| `ellipsis` | more, actions, dots | 1.0.0 |
| `ellipsis-vertical` | more, actions, dots, collapsed menu | 1.0.0 |
| `envelope` | communication, email, correspondence, message, inbox, mail | 1.0.0 |
| `expand` | enter full screen | 3.0.0 |
| `eye` | password, visible, show | 1.0.0 |
| `eye-slash` | password, hidden, not visible, hide | 1.0.0 |
| `face-frown-slight` | emoji, frown, sad, dissatisfied, unhappy | 2.1.0 |
| `face-meh` | emoji, neutral, meh | 2.1.0 |
| `face-smile` | emoji, happy, smile, grin, satisfied | 2.1.0 |
| `family` | family, families | 1.0.0 |
| `file` | doc, document, file, paper | 1.0.0 |
| `file-check` | doc, document, success | 1.0.0 |
| `file-export` | doc, document, export, send | 1.0.0 |
| `file-import` | doc, document, import | 1.0.0 |
| `file-invoice` | doc, document, billing, invoice, file | 1.0.0 |
| `file-invoice-dollar` | doc, document, billing, currency, money, current session, report, file | 1.0.0 |
| `file-lines` | docs, documents, files, multiple reports | 1.0.0 |
| `file-pen` | edit, doc, document, file, write | 1.0.0 |
| `file-plus` | add, doc, document, add file, new file, add page | 1.0.0 |
| `files` | docs, documents, multiple files, multiple reports | 1.0.0 |
| `filter` | filter | 1.0.0 |
| `fingerprint` | login, biometric, face id, fingerprint, identity | 3.0.0 |
| `folder` | organization, organize, file folder | 1.0.0 |
| `folder-user` | organize, organization, admissions, user information | 1.0.0 |
| `function` | math, function, calculate, calc | 2.1.0 |
| `gear` | settings, configuration | 1.0.0 |
| `grid` | application, app, select app | 1.0.0 |
| `grid-2` | admin, dashboard, app view, cashier function, grid view | 1.0.0 |
| `grip-dots` | drag, column, horizontal, reorder | 1.0.0 |
| `grip-dots-vertical` | drag, row, vertical, reorder | 1.0.0 |
| `hands-holding-child` | child care, childcare | 1.0.0 |
| `heart` | favorite, like, love | 1.0.0 |
| `heart-solid` | favorited, liked, loved | 1.2.0 |
| `house` | home, main, app, household | 1.0.0 |
| `id-badge` | employee, staff, faculty | 1.2.0 |
| `id-card` | user, data, identity, credential | 1.0.0 |
| `image` | picture, image, photo | 1.0.0 |
| `italic` | italic, formatting, font, styling, wysiwyg | 2.1.0 |
| `language` | i18n, internationalization, translate, language | 1.0.0 |
| `laptop-mobile` | phone, computer, responsive, devices, portal, family portal | 1.0.0 |
| `layer-plus` | auto-create, add multiple, add layers | 3.3.0 |
| `link` | hyperlink, link | 1.0.0 |
| `list` | list, unordered list, bullets | 1.0.0 |
| `list-check` | checklist, check list, checks | 1.0.0 |
| `list-ol` | ordered list, numbered list, steps | 2.1.0 |
| `list-ul` | list, unordered list, bullets | 2.1.0 |
| `location-dot` | map, pin, location, point | 1.0.0 |
| `lock` | locked, restricted | 1.0.0 |
| `magnifying-glass` | search, zoom | 1.0.0 |
| `magnifying-glass-minus` | zoom out | 2.1.0 |
| `magnifying-glass-plus` | zoom in | 2.1.0 |
| `memo` | note, disclosure, disclosures, memo | 1.0.0 |
| `merge` | join, combine, merge, integrate | 2.1.0 |
| `message-lines` | comment, communicate, message, conversation | 1.0.0 |
| `messages` | comments, communications, conversation, messages | 1.0.0 |
| `minus` | remove (alternate) | 1.0.0 |
| `mobile` | phone, device, mobile | 1.0.0 |
| `money-bill` | payment, currency, money, single payment | 1.0.0 |
| `money-bill-transfer` | transaction, transfer, money, currency, recurring | 1.0.0 |
| `money-bills` | payments, currencies, realtime, real time payment, transactions | 1.0.0 |
| `money-check` | scan, money, check | 1.0.0 |
| `money-check-pen` | manual, check, entry | 1.0.0 |
| `money-from-bracket` | deposit, money, currency, departmental deposit | 1.0.0 |
| `note` | note | 1.2.0 |
| `octagon-exclamation` | error, stop, warning, alert | 1.0.0 |
| `palette` | style, branding | 1.0.0 |
| `paper-plane-top` | send, message, email | 1.0.0 |
| `paperclip` | attachment, attach | 1.0.0 |
| `party-horn` | celebration, kudos, positive, achievement, success | 1.0.0 |
| `pen-to-square` | edit | 1.0.0 |
| `percent` | percent | 1.0.0 |
| `person` | family, individual | 1.0.0 |
| `phone` | number, call, phone | 1.0.0 |
| `play` | play, start, begin | 1.2.0 |
| `plus` | add, new | 1.0.0 |
| `plus-minus` | add or remove | 2.1.0 |
| `prescription-bottle-medical` | medication, pills, prescription | 1.0.0 |
| `print` | print | 1.0.0 |
| `puzzle-piece` | integration, piece | 1.0.0 |
| `qrcode` | scan, QR code | 1.0.0 |
| `receipt` | sales, miscellaneous sales, receipt, proof of purchase | 1.0.0 |
| `reply` | reply, revert | 1.2.0 |
| `school` | school, institution, building | 1.0.0 |
| `share` | share | 1.0.0 |
| `shield` | security, admin, permissions | 1.0.0 |
| `shop` | store, mobile register | 1.0.0 |
| `sitemap` | tenant hierarchy, hierarchy | 1.0.0 |
| `sliders` | adjust, adjustment, option | 1.0.0 |
| `snooze` | nap, sleep, delay, snooze | 1.0.0 |
| `sparkles` | ai, artificial intelligence, auto | 2.0.0 |
| `spinner-third` | load, loading | 1.0.0 |
| `square-dashed` | default, empty | 1.0.0 |
| `star` | favorite, activity, special | 1.0.0 |
| `star-of-life` | emergency, 911 | 2.0.0 |
| `star-solid` | favorited, activity | 1.2.0 |
| `table` | table, format table | 2.1.0 |
| `table-layout` | dashboard, table, template | 3.4.0 |
| `tag` | label, price, tag, category | 1.0.0 |
| `tags` | labels, tags, prices | 1.0.0 |
| `telescope` | observation, watch | 1.0.0 |
| `thumbtack` | pin, favorite, save | 1.0.0 |
| `toilet` | restroom, potty, bathroom | 1.0.0 |
| `trash-can` | delete, remove and delete | 1.0.0 |
| `triangle-exclamation` | warning, alert, notice | 1.0.0 |
| `underline` | underline, formatting, font, styling, wysiwyg | 2.1.0 |
| `unlock` | unlock, allow | 3.2.0 |
| `upload` | upload, browse files | 1.0.0 |
| `user` | user, person, account, profile | 1.0.0 |
| `user-gear` | user settings, configure user | 3.0.0 |
| `user-graduate` | student, alumni | 1.0.0 |
| `user-lock` | permission, permissions, user rights | 1.0.0 |
| `user-magnifying-glass` | user search, user lookup | 3.4.0 |
| `users` | users, group, people | 1.0.0 |
| `utensils` | lunch, breakfast, meal, food, menu, cafeteria, dining, eat | 1.0.0 |
| `video` | movie, film, video, live | 1.0.0 |
| `xmark` | close, dismiss | 1.0.0 |
---
# Icon Library Changelog
The NPDS Icon Library package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## 3.4.0
### Features
- added new `user-magnifying-glass` and `table-layout` icons
## 3.3.0
### Features
- added new `layer-plus` icon
### Code Refactoring
- added script to generate manifest from Figma export instead of CSV file
## 3.2.0
### Features
- added new `unlock` icon
## 3.1.0
### Features
- added new `delete-left` icon
### Documentation
- added Figma Code Connect files for icons
### Continuous Integration
- updated Figma CI pipeline to include icon figma files
## 3.0.0
### BREAKING CHANGES
- replaced `arrow-up-right-from-square` with `arrow-up-right`
### Features
- added new `arrow-progress`, `box-archive`, `compress`, `expand`, `fingerprint`, and `user-gear` icons
## 2.1.0
### Features
- added new `arrow-down-from-line`, `arrow-up-from-line`, `bold`, `face-frown`, `face-meh`, `face-smile`, `function`, `italic`, `list-ol`, `list-ul`, `magnifying-glass-minus`, `magnifying-glass-plus`, `merge`, `plus-minus`, `table`, and `underline` icons
## 2.0.0
### BREAKING CHANGES
- replaced `right-from-bracket` with `arrow-right-from-bracket`
- replaced `right-to-bracket` with `arrow-right-to-bracket`
- removed `pen`, `share-from-square`, `sort`, `sort-down`, and `sort-up` icons
### Features
- added new `arrow-left-from-line`, `arrow-right-from-line`, `arrow-up-arrow-down`, `badge-check`, `building-columns`, `car-side`, `sparkles`, and `star-of-life` icons
## 1.2.0
### Features
- added new `children`, `circle-question`, `heart-solid`, `id-badge`, `note`, `play`, `reply`, `sliders`, and `star-solid`, icons
### Build System
- excluded 'in library' csv column from `index.json` manifest
## 1.1.1
### Bug Fixes
- excluded `README.md` and `CHANGELOG.md` from `pathFilters` in `version.json` to avoid bumping the version number when only those files are changed
## 1.1.0
### Features
- added `icons.csv` file with icon metadata that generates an `index.json` manifest on build using the `csvtojson` library
### Documentation
- added CHANGELOG
---
# Avatar
`Development`
## Avatars represent a user or entity.
``[Source](https://github.com/nelnet-nbs/npds-lib-design-system/blob/main/packages/npds-components/src/components/avatar/avatar.ts)|[Figma](https://www.figma.com/design/g4KSDEnxR7gxIFfwpPn7I5/NPDS?node-id=3557-8234)
## Usage
> This component is currently in development. It should not be used in production environments and is subject to breaking changes at any time. It may have incomplete documentation, may not be fully accessible, and may not have complete test coverage.
Avatars provide a unique visual representation of a person, account, organization, or entity.
### Sizes
The `size` property is used to set the size of an avatar. There are four avatar sizes: `sm`, `md`, `lg`, and `xl`.
`md` is the standard avatar size and will be applied by default if no size is explicitly set.
### Colors
The `color` property is used to set the color variant of an avatar. There are six avatar colors: `gray`, `blue`, `green`, `purple`, `red`, and `yellow`.
`gray` is the standard avatar color and will be applied by default if no color is explicitly set.
### Icon
The `icon` property is used to render an icon within the avatar.
- The `icon` property is used to specify a glyph name from the [NPDS Icon Library](https://npds.nelnet.com/llms/icons-library-documentation.md).
- If the glyph name specified isn't in the icon library, a placeholder icon will be rendered instead. An error will also be present in the console.
`user` is the standard avatar icon and will be rendered by default if no icon is explicitly set.
## Best Practices
### Align avatars with their content
Avatars are vertically center-aligned with their complementary text, like a person's name or a group of text (like name and email address on two lines).
### Avatars and icon buttons aren't interchangeable
Use avatars only to represent specific people or entities. Avoid using avatars to trigger actions or to achieve a specific background color for an icon button.
### Ensure avatars are visually distinct
Whenever possible, choose a unique combination of color and content to represent different entities when using multiple avatars in a tight space (tables, for example). Distinct visual attributes keep users from grouping avatars together as the same entity.
## Code
### Installation
Visit the [Installation](https://npds.nelnet.com/llms/getting-started-installation-documentation.md) page to learn how to use NPDS components in your project.
### Importing
Import the Avatar component using:
```
import "@nbs/npds-components/avatar";
```
### Code Connect`Connected`
When using Code Connect, Figma's Dev Mode displays dynamic and accurate snippets for each instance of a component. A Code Connect snippet can be copied and pasted directly into your project.
## API
### Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| size | `"sm" | "md" | "lg" | "xl"` | `"md"` | Sets the size. |
| color | `"gray" | "blue" | "green" | "purple" | "red" | "yellow"` | `"gray"` | Sets the color variant. |
| icon | `string | undefined` | `` | Renders the specified glyph. |
---
# Badge
`Ready`
## Badges show counts on navigation items and icons.
``[Source](https://github.com/nelnet-nbs/npds-lib-design-system/blob/main/packages/npds-components/src/components/badge/badge.ts)|[Figma](https://www.figma.com/design/g4KSDEnxR7gxIFfwpPn7I5/NPDS?node-id=2002-14849)
## Usage
Badges are used as visual indicators that display a numerical count. In most scenarios, a badge will be used indirectly by using another component that incorporates a badge.
### Variants
The `variant` property is used to set the color variant of a badge.
- `informative` badges should be used when no additional meaning needs to be conveyed.
- `positive` badges should be used to indicate new, approved, or otherwise positive items.
- `negative` badges should be used to indicate errors or issues that require immediate attention.
`informative` is the standard badge variant and will be applied by default if no variant is explicitly set.
### Value
The `value` property is used to set the numerical value of a badge.
### Max
The `max` property is used to set the maximum numerical value displayed on a badge. While not required, setting a logical `max` value is recommended to prevent excessively lengthy badges.
## Best Practices
### Avoid long numbers
Set a logical max value so large numbers do not affect layout. In the rare case where a large number needs to be displayed, be sure to plan for how a badge’s size will impact other components.
### Don’t overlay badges
Badges should be placed to the right of and vertically aligned to the middle of the content they enhance, and not overlay or obscure any part of that content.
## Code
### Installation
Visit the [Installation](https://npds.nelnet.com/llms/getting-started-installation-documentation.md) page to learn how to use NPDS components in your project.
### Importing
Import the Badge component using:
```
import "@nbs/npds-components/badge";
```
### Code Connect`Connected`
When using Code Connect, Figma's Dev Mode displays dynamic and accurate snippets for each instance of a component. A Code Connect snippet can be copied and pasted directly into your project.
## API
### Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| value | `number` | `0` | Sets the numerical value. |
| variant | `"informative" | "positive" | "negative"` | `"informative"` | Sets the color variant. |
| max | `number | undefined` | `` | Sets the maximum value to display. If the `value` exceeds the `max`, a `+` will be added after the number. |
---
# Banner
`Ready`
## Banners display prominent messages with associated meaning.
``[Source](https://github.com/nelnet-nbs/npds-lib-design-system/blob/main/packages/npds-components/src/components/banner/banner.ts)|[Figma](https://www.figma.com/design/g4KSDEnxR7gxIFfwpPn7I5/NPDS?node-id=1097-12395)
## Usage
Banners are used to communicate important messages to users. They can be used to display feedback, warnings, errors, and general announcements.
### Variants
The `variant` property is used to set the semantic variant of a banner. Each variant has an associated color and icon.
- `informative` banners should be used for general information or when no additional meaning needs to be conveyed.
- `positive` banners should be used for messaging that involves successful or otherwise positive events.
- `notice` banners should be used for warnings or information that requires attention but isn't critical.
- `negative` banners should be used for errors or issues that require immediate attention.
`informative` is the standard banner variant and will be applied by default if no variant is explicitly set.
### Heading
The `heading` property is used to render an optional heading above the banner text.
- A heading is recommended in most instances but can be omitted when the banner message is simple and concise.
### Dismissible
The `dismissible` property is used to render a dismiss button on a banner.
- The dismiss button dispatches a custom `npds-dismiss` event when clicked.
- The `npds-dismiss` event should be used to dismiss the `` element from the DOM.
### Action
The `action` slot should be used to display an optional [Button](https://npds.nelnet.com/llms/components-button-documentation.md) component below the banner text.
- A banner should only contain a single button that clearly communicates the action a user should take.
- A banner button should only use the default `outlined` appearance and `secondary` variant.
## Best Practices
### Avoid large blocks of text
Titles should be short but informative, and not end with punctuation. Use clear and concise messaging and avoid technical jargon unless it is appropriate for the audience.
### Banners complement their relevant content
Banners should display above and be the same width as the content to which they relate.
### Don't automatically dismiss banners
A banner should persist indefinitely until a user intentionally dismisses it by clicking the optional dismiss button.
### Toasts for repetitive actions
Increase usability by using a [toast](https://npds.nelnet.com/llms/components-toast-documentation.md) instead of a banner for repetitive actions.
## Code
### Installation
Visit the [Installation](https://npds.nelnet.com/llms/getting-started-installation-documentation.md) page to learn how to use NPDS components in your project.
### Importing
Import the Banner component using:
```
import "@nbs/npds-components/banner";
```
### Code Connect`Connected`
When using Code Connect, Figma's Dev Mode displays dynamic and accurate snippets for each instance of a component. A Code Connect snippet can be copied and pasted directly into your project.
## API
### Slots
| Name | Description |
| --- | --- |
| default | The banner text. |
| action | The optional banner action. This slot should be used for a single `` component. |
### Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"informative" | "positive" | "notice" | "negative"` | `"informative"` | Sets the semantic variant. |
| heading | `string | undefined` | `` | Renders a heading above the banner text. |
| dismissible | `boolean` | `false` | Renders a dismiss button that dispatches a custom event when clicked. |
### Events
| Name | Type | Description |
| --- | --- | --- |
| npds-dismiss | `CustomEvent` | Dispatched on a dismissible banner when the dismiss button is clicked. This event should be used to remove the element from the DOM. |
| dismiss | `CustomEvent` | **Deprecated:** Use `npds-dismiss` instead. |
---
# Breadcrumbs
`Designed`
## Breadcrumbs show users their location within the site hierarchy.
## Usage
> This component has been designed and is planned for development. Until its status is updated, do not use this component in designs scheduled for development.
Breadcrumbs give users a clear path to move between levels, showing up to five page titles that reflect the site hierarchy. Each title acts as a direct link to navigate to that level.
## Best Practices
### Breadcrumbs get Title Case
Navigational elements and H1 page titles are written in title case, so breadcrumbs are always written in title case. Capitalize the first letter of most major words in titles; skip short articles, conjunctions, and prepositions unless they’re the first or last word in a page title.
### Breadcrumbs stay the same even with multiple paths
Because a page can only exist in a single spot within the application, its breadcrumb trail will always be the same even if there are multiple ways to get to the page (for example, shortcut buttons).
## API
---
# Button
`Ready`
## Buttons let users take action and make choices.
``[Source](https://github.com/nelnet-nbs/npds-lib-design-system/blob/main/packages/npds-components/src/components/button/button.ts)|[Figma](https://www.figma.com/design/g4KSDEnxR7gxIFfwpPn7I5/NPDS?node-id=7034-28425)
## Usage
Buttons are used for interface actions and links to other content.
### Appearances
The `appearance` property is used to set the visual appearance of a button.
- `outlined` buttons carry less visual weight and should be used for the majority of actions on a page.
- `filled` buttons should be used when more visual emphasis is needed.
`outlined` is the standard button appearance and will be applied by default if no appearance is explicitly set.
### Variants
The `variant` property is used to set the color variant of a button. The `variant` property is used in combination with the `appearance` property to render a variety of button styles for different use cases.
#### Primary
`primary` buttons should be used for important actions that are recommended to the user.
- `outlined` primary buttons should be used for the recommended action on a **section** or **item**.
- `filled` primary buttons should be used for a singular recommended action on a **page** or **dialog**.
#### Secondary
`secondary` buttons should be used for supporting actions or when no single action is recommended to a user. `secondary` is also the standard button variant and will be applied by default if no variant is explicitly set.
- `outlined` secondary buttons should be used for multiple supporting actions, or when a `filled` button is nearby.
- `filled` secondary buttons should be used when a supporting action needs more visual emphasis.
#### Negative
`negative` buttons should only be used for destructive actions that cannot be undone or will result in the deletion of data.
- `outlined` negative buttons should be used for a destructive action on a **section** or **item**.
- `filled` negative buttons should be used for a singular destructive action on a **page** or **dialog**.
### Disabled
The `disabled` property is used to prevent interaction with a button.
> Disabled buttons are removed from the tab order and cannot receive focus or clicks. This can cause issues with assistive technology, so `disabled` should be avoided whenever possible. Instead, use validation or other messaging to guide users.
### Sizes
The `size` property is used to set the size of a button.
- There are three button sizes: `sm`, `md`, and `lg`.
`md` is the standard button size and will be applied by default if no size is explicitly set.
### Fluid width
The `fluid` property is used to render a full width block-level button.
### Icon
> For icon-only buttons, use the [Icon Button](https://npds.nelnet.com/llms/components-icon-button-documentation.md) component to ensure proper accessibility and styling.
When the `icon` property is present, an icon will be rendered to the left of the button text.
- The `icon` property is used to specify a glyph name from the [NPDS Icon Library](https://npds.nelnet.com/llms/icons-library-documentation.md).
- If the glyph name specified isn't in the icon library, a placeholder icon will be rendered instead. An error will also be present in the console.
### Menu
The `menu` property is used to render a down chevron icon on a button that should trigger a menu.
### Loading state
The `loading` property is used to render a spinner icon in place of the original content while retaining the original width. Buttons in a loading state are also disabled to prevent user interaction.
### Links
When the `href` property is present, a button will be rendered as an `` element instead of a `