mincho

Natural CSS in TypeScript

[!WARNING] This project is still in WIP, which means it is not ready for production.

Demo with StackBliz

Documentation

See @mincho-js/css README.

Motivation

Rethinking CSS in JS

It started with contemplation on approaches and management methods for CSS styling.

Methodologies for CSS selectors can be largely divided into visual hierarchy and semantic hierarchy.

The visual hierarchy uses visual names like .text-red { color: red; },
while the semantic hierarchy uses meaningful names like .error { color: red; }.

Due to these characteristics, the methods of achieving goals also differ.
For example, what if we need to create various designs with the same content, like as CSS Zen Garden?

The visual approach would keep the CSS fixed but change the HTML to achieve the goal,
while the semantic approach would keep the HTML the same but change the CSS to achieve the goal.

As a practical example of dealing with visual hierarchy, there's Tailwind CSS, and for semantic hierarchy, there's Stitches.
If you look at Tailwind's Text Color, you can see it's visually intuitive with classes like text-black, text-white.
Stitches has invented an API called Variants, which aligns with the original purpose of CSS classes as element identifiers[1, 2], and makes it very easy to apply BEM.

I believed that these two approaches could reconcile and form a dialectical triad.

Just like how the cool and refreshing taste of mint harmonizes with the sweetness of chocolate in mint chocolate!

Vision

"Build your own design system" is our vision.
We aim not only to integrate visual hierarchy and semantic hierarchy but also to improve the design process itself.

This is achieved under several principles:

Be declarative rather than listing logic
The API of each layer should be isomorphic
Expression and content presuppose each other, so they should be considered
If the hierarchy (perspective) is different, the law of excluded middle applies
Consider both developers and designers

Our CSS in JS framework will consist of 5 layers (Literal, Theme, Atomic, Variant, Styled Component).

Literal: Provides various CSS-specific syntax of CSS preprocessors, considering the syntactic limitations of JavaScript
Theme: Design token values and customization for Color, Typography, Spaces, etc.
Atomic: Atomic styles that map to visual values
Variants: Styles for reusable blocks
Styled Component: Binding with JSX components

This can also be compared with State[1, 2]:

JSX: Binds HTML and JS
State hook: Logic independent of view platform
Behavior hook: Handles events, accessibility, internationalization, etc. for platform APIs (DOM, React Native, etc.)
Headless Component: Provides binding of JSX and hooks for use
Component: Component blocks including design

However, since we cannot provide all features from the beginning, we plan to achieve them step by step.

Natural CSS in TypeScript: We will bind various CSS preprocessing features to be specialized for TypeScript.
CSS in JS for Scalable: We will achieve the integration of visual hierarchy (AtomicCSS) and semantic hierarchy (Variants), which was the original goal.
Build your own design system: It functions as a framework for creating design systems through design token management and Figma plugins, among others.

Features

Currently, most of the features are related to the CSS preprocessor.

CSS Literals: Expressing more natural CSS in TypeScript.
CSS Nesting: Expressing better nesting and referencing.

Contributing

Interested in contributing?
We have a contributing guide.

If you need support, ask in discussions.
Participation is open. Welcome! :hugs: :hugs:

Support

Do you have any questions?
Feel free to ask questions in discussions.

Inspired

This project was inspired by the syntax and functionality of various projects.
Without them, this would not be possible!!

Special Thanks

Vanilla Extract: This project is based on vanilla extract. It has a very fancy API.
Sass: Inspired so many different features variables, nesting, parent selector ...etc

mincho-js / mincho

readme