Foundations
STUDS Styles
This is a draft document. There are lots of broken links, notes to myself to add or update things, and probably some bullet points that make no sense to the surrounding content. Welcome to my brain. This is also an , so please reach out to me with comments, questions, and suggestions.
Introduction to the P -M CSS methodology
One constant will always remain true: designs change. Whether it’s the whims of fashion, the needs of users, or the desire for design to just be “new”, change is constant. The P -M methodology understands this, and is based around naming components and elements based on their function and purpose, instead of how they look. See Appendix A for a deeper dive into why purpose instead of appearance is the best solution to future-proof a design system. P -M is also designed to help reduce specificity on base styles to make it easier to override them if needed. The two basic principles are:- Element and component classes are named by their purpose
- Variations on the base style are made using modifier classes
Elements and components are named for their purpose.
If a component such as a Radio Button will only ever be a radio button, then there is no need to create an additional class calledradio. However, the styles for a <button> are also often assigned to an <a href> link, so in this case it makes sense to create a button class. The button class has all the defaults for every aspect of the button: background color, text color, border radius, border color, drop-shadow. Additional default styles for :hover and :active states are also defined.
Variations on the base style are made using modifiers.
Modifiers start with a- dash. In the case of the button class, the modifiers might be -cta, -primary, -ghost, -link, etc. A CTA button would be button -cta see Appendix B for a comparison between P -M and BEM naming conventions.
While modifiers can be local to an element or component, they can also be global. For instance, the design system states that disabled elements are 60% opacity, interactivity is disabled, and the “no” cursor shows when hovered. This can be set globally, with a -disabled modifier (for better coverage, the selector would actually be [disabled], .-disabeled {}).
Another possibility for a global modifier would be -primary. For elements such as buttons, checkboxes, radio buttons, and badges, they should all have the same attributes for their primary variation: the background color of the button would be the same as the color for the checkboxes, radio buttons, and badges. And the text color of the button would be the same as the text on the badge, the check in the checkbox, or the border of the radio button.
By setting these properties globally, they all carry through to the elements as needed. And because they’re on the global scope, which has a very low specificity, then they are easy to override in the component’s CSS scope. More on scope and overrides in the CSS Cascading Layers section
Document and folder structure
- colors are defined in their own document
- metrics, such as spacing and corner radius, are in another document
- theme is in yet another document
- components are in individual files in a components directory
- Icons contains any custom icons that are in addiiton to the icon set we are using. Currently, that is the Material icon set
studs-styles.cssis where cascading layers and order is being defined (see CSS Cascading Layers for more details). This file must be outside of the Sass compiler, as Sass interprets the@importrules incorrectly, and changes the order of imports. This is a known bug with the Sass-dart compiler.- Components directory contains individual files for each component, e,g, button.scss, badge.scss, dropdown.scss, etc.
- Utilities directory contains the majority of the files that make this system work. colorRamps, fonts, metrics, mixins, and the normalize.css files are here.
base.scssis where all the basic page styles are. Elements that aren’t components and aren’t considered “styled elements” are styled here. e.g.<p>,<em>,<strong>,<abbr>, etc.overrides.scssis where devs can put any style overrides, extended styles, or addition styles.themes.scssis where all color tokens are defined and used.
Theming Capabilities
F -M is ready for light and dark themes in addition to other custom themes. For instance, the marketing site might want to have a modified color palette for a spring sale, or perhaps a winter theme for the holidays. Or perhaps each web app is to have a different base color palette corresponding to areas of relevance. Apps related to Fasteners and Supports might be blue, but Outdoor Structures might be a purple color palette. In addition to the base color palette, there are accessibility considerations in each theme for higher contrast color combinations. For instance, if a color combination such as a very pale gray background and a medium gray text would fail WCAG contrast tests, this doesn’t mean it can’t be used in the color system. It just means we also need a higher contrast alternative for when a user has selected “use high contrast themes” in their browser or in their system. When this is the case, the high contrast options will be used instead. If the user has turned off motion and transitions in the system or browser, then all animations in the CSS will be reduced to 0 seconds in length. Tokens are also named by their purpose: surface, action, control, feedback.- surface: the basic application properties, such as page background color, text color, border colors, etc.
- action: elements such as buttons that perform actions
- control: checkboxes, radio buttons, and sliders are examples of controls
- feedback: alerts, warnings, success and info elements are all considered feedback
--surface-backgroud or --action-selected-foreground
In addition to colors, other display properties such as elevation (usually shown with varying levels of drop shadows), corner radius, border thickness, and spacing (used for padding and margins) are also defined.
CSS Cascading Layers
F -M relies heavily on CSS Cascading Layers (see also: MDN docs and Getting Started). Once the loading order has been established, we can load additional styles to any layer without having to worry about css load order. Of course, the cascade order is still important within each layer, but this makes it easier to make sure all base styles are loaded first, before modifying or customizing those styles for a specific application. More importantly, CSS Cascading Layers makes it much easier for end users to override styles without the need for!important. CSS Layers helps return !important to it’s original purpose.
The layer loading order is reset, utilities, fonts, themes, base, components, layout, overrides
- reset: a simple browser reset using normalize.css
- utilities: includes all the basics such as colors, metrics, tokens, and more
- fonts: where font faces are defined
- themes: foundational colors and tokens. see Theming Capabilities for more details
- everything here is a CSS custom property to make theming and accessibility options easier.
- tokens are also named by their purpose to make updates easier and more logical.
- other themes are also possible. For example, an app that needs to follow the basic rules of the design system, but with different colors to match a co-branded partner’s colors (dark blue instead of SST orange). Or perhaps a “spring-sale” or “winter-holiday” themed temporary takeover for the marketing site.
- base: basic page styles: line height, fonts, and all simple HTML elements that aren’t considered a component, such as
<p>,<em>,<h1>,<h2>,<h3>etc. - components loads all the individual components styles. The components file is another cascading layer within the main layer. While it shouldn’t be necessary, if needed a new component can be added to the components layer with
@layer components.my_new_component{ }. - layout will contain some layout helpers and utilities. Currently, these are still being designed, but the plan is to make responsive multi-grid layouts, app shells, and other utilities to help end-users with page layout.
- overrides is a blank file. This is where the end user can put whatever styles they need to override or extend any of the other styles. Since this layer has been named, devs are also welcome to use their own files, and add them to the overrides using
@layer overrides.class-name-to-modify{}
Examples
Tokens are named for their purpose.--action-background, -secondary-foreground, --focus-color, and --disabled are all examples of purpose-based tokens. See Theming Capabilities for more about this, including light and dark themes, as well as app-based overrides.
Simple Component
A good example to start with are buttons because there are so many different styles and functions of a button. But under it all, they are still just a button that’s been styled differently. The pieces of a button’s styles are:@TODO: example image and functioning button
-secondary, -outline, -destructive, -ghost, -link.
For secondary there aren’t a lot of changes from default, so we just need to add this after the &:active selector.
outline is similar, but with a border.
link button has a few extra styles.
@TODO examples of all buttons
THIS HAS NOT BEEN IMPLEMENTED
As part of the metrics, there are some relative t-shirt sizing which can be applied to most elements.Currently, STUDS only has a light theme implemented. However, the framework is there to add a dark theme once it’s been fully designed. Right now, we are forcing a light theme even if a user has chosen dark theme in their OS or browser settings.note Why define both variables and utility classes? consistency. To make sure that mediumBecause they’re based on the font size of the element, they can be applied as a utility class. So-mdis the same no matter where it’s used, and that a-mdclass is available when needed.<button class="button -secondary -md">is all you need to make a slightly smaller button. That being said, utility classes are generally avoided, because they are describing what an element looks like, instead of it’s function or purpose. However, the t-shirt sizing is here as a fallback. In most cases, the sizes would be changed on the component’s style overrides instead of assigning the class. For instance, if this was a button in a table header and it should be slightly smaller than the default, then styles for the button might beEND OF NOT IMPLEMENTED
Complex Component
Here’s a simple example card component:card components will be elements on a css grid, and the header, .content, and footer will be subgrid items for a clean layout.
@TODO: selector for card wrapper and card subgrid
<div class='card -employee -lead'>.
Since and employee card has only a couple changes or additions to the base card styles, using modifiers makes this easier to code. And then the -lead styles are just a couple overrides that works with the -employee and card selectors. See AppendixB. Why not BEM?* for an example of what BEM-style naming would be for this card component.
Appendix
A. Why "purpose" instead of "appearance"?
A. Why "purpose" instead of "appearance"?
The most important thing to remember when designing a website is understanding that designs change. Not just during the initial design phase, but over time. In a week, a month, or a couple years, design trends change, and designers change their minds about what they want things to look like and how they behave.While A CTA button may be orange and pill-shaped now, it may change to charcoal gray and rounded rectangle in the future. In fact, this is exactly what happened with STUDS styles going from versions 1 and 2 to STUDS 3. If CTA buttons had been given class names such as
.button .button-cta .button-orange__rounded, we would have had to go back to every place a button was used and update the class names on each of those buttons. But instead, we used .button -cta, and the only place those styles needed to be updated was in a single component style sheet.By using this approach, it removes using “look and feel” in class names, and instead concentrates on what a thing actually is or does. Just using button -cta is a lot cleaner and future-proof.Let the styles do what the styles do best… style things.B. Why not BEM?
B. Why not BEM?
BEM was designed to increase specificity, not reduce it. BEM encodes hierarchy in the class name, including information thats already in the HTML structure, creating highly specific classes that are difficult to override or modify. The styles are so tightly scoped that it’s difficult to reuse styles across different blocks without duplication. BEM also creates a tag soup in the HTML that is difficult to read or understand.Instead of using highly specific names, use the browser’s capabilities and built in HTML naming. It’s easier on the browser, reduces the need for developers to actually think of names for everything.Additional reading:
- Time to Stop Using BEM - Fotis Adamakis
- BEM Is Terrible - an introduction the GPS methodology
- The author, Jeff Escalante, is describing their own take on a replacement for BEM, which they call “GPS”. However, the reasons for not using BEM are still relevant to this discussion
@TODO: BEM examples compared to P -M
C. Why not Tailwind?
C. Why not Tailwind?
One of the biggest problems with Tailwind is how shortsighted it is. Class names are all utility classes. The developer describes what an element looks like, and also how it’s laid out on the page, all within the html. When designs change, and they always change, every instance of that element must be updated. In addition, many modern CSS capabilities aren’t available in Tailwind, or the process for using them is even more complex that if you were just using vanilla CSS.For example, to create a simple grid with auto-layout in tailwind, you would need to create the HTML and classes like this:And then create custom Tailwind configuration for the Once created, that auto-fit has a fixed To bring this fully into the P -M methodology, we would add just one more class to the grid div This way, we set a default style for all elements with a grid, and a base style for all the cells inside. Because we’re using the tokens, when a light, dark, custom, or high contrast theme is used, it will inherit all the correct color for that theme automatically, without having to define those additionally in the HTML utility classes.When the design system changes – perhaps the colors change to a different shade, or the grays become slightly darker or lighter depending on current trends – those tokes will be updated in the Then each div inside the grid would need those classes.Using the above example, if the we would need to update every class list here to change the background colors, the dark theme colors, and the border radius size. On every cell.
grid-cols-auto-fit classminmax(200, 1fr). If you want to change the minmax sizes for a different grid, you’ll need to create additional utility classes for each minmax size you might need.Whereas with vanilla CSS, it would look like this:<div class="gird -display>. I’m calling this grid “display”, just as an example. Our styles would look like this:_themes file, and the colors will automatically update on the grid elements without ever having to touch the CSS. If the corner radius changes to a squared corner, then all we need to do is update a single line in the CSS and every grid cell automatically updates.If the element with the grid class also has a -display modifier, then it will get the themed overrides (which also have light, dark, custom, and high contrast themed variations). Because we set up locally scoped custom properties, all we need to do is change those values on the local root, and every child of that element using those variables will get the updated values.To do just light and dark themes using Tailwind, you would need to make sure darkMode is enabled in your config file.- Tailwind is shortsighted and doesn’t understand that designs change
- Tailwind takes longer to learn than clean and modern CSS
- Tailwind is difficult to read and uses convoluted rules for theming
- Tailwind is always behind on newly available CSS and HTML capabilities.
If your tools don’t let you use the platform, that’s not a tool. It’s an obstacle. When new features come out in HTML and CSS, and you’re not allowed to use them because you’re waiting for the update to version 3… then you’re using the wrong tool. Find a different tool
- Miriam Suzanne, 2025
D. Accessibility
D. Accessibility
- using REMs for everything
- if a user sets a larger base font size, then everything will scale according to that base font
- high contrast variations on themes
- reduced motion
E. Resources and further reading
E. Resources and further reading