facebookincubator / infima

A UI framework that provides websites with the minimal CSS and JS needed to get started with building a modern responsive beautiful website

Infima ·

⚠️ Infima is not yet ready for production use and is being developed alongside Docusaurus 2.

A modern styling framework for content-driven websites 🔥.

Features

• Theming - Create websites with built-in support for theming and dark mode
• Modern - Built using modern CSS methodologies - CSS variables, PostCSS and BEM naming
• Modular - Import only the CSS for the components which you need

Background

While building Docusaurus 2, we found that we needed styling for a documentation website as part of the default theme. We could bake the styling into the default theme such that it was only used by Docusaurus websites, but in the usual Facebook fashion, we decided to separate out the CSS layer into a separate project such that websites interested in adopting a documentation-site styling could use it too.

This project is being built alongside Docusaurus 2 and is still in the alpha stage, so using only this project in production is not recommended. Class names and CSS variable names might change in future (but will be documented in the CHANGELOG).

License

Infima is MIT licensed.

infima's Issues

using docusaurus - problem with css from using it

Hello! I'm working on a project using the source code of docusaurus (last version), I can add for example DocSidebar into my project, and use it, but the styles are missing. tried creating a rule css on webpack on the node_modules folder but is not taking css from it. I can see each component has new css classes like "styles-module___abcd" abcd changes every time. I assume it is infima that are generating those, but how can I use the css generated inside the docusaurus package in my project? Thanks!

feat: add CSS reset

Redesign shadows

The Infima shadows are not very convenient to use currently.

The lw shadow is not very visible, and the difference between --lw and --md is huge:

In practice, Docusaurus almost only use --lw, so it seems safe to re-adjust other shadows

Good resource on shadow design:

• https://www.joshwcomeau.com/css/designing-shadows/
• https://twitter.com/JoshWComeau/status/1458813277056688139

Upgrade to Node 12

Docusaurus moved to Node 12, as Node 10 EOL is soon.

Infima requires Node 10 to build correctly and fails on Node 12.

This is annoying because we can't use latest Docusaurus on Infima website (including deploy previews).

We should make sure Infima is able to build on Node 12 or we won't be able to upgrade the Infima website to latest Docusaurus.

yarn install v1.22.5
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
error @docusaurus/[email protected]: The engine "node" is incompatible with this module. Expected version ">=12.13.0". Got "10.23.3"
error Found incompatible module.
info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

Question about roadmap

I would like to ask if there is a roadmap for this framework? If there a way I could contribute? For the past four years I have been working on a very similar architecture and components for UI development using OOCSS, BEM and ITCSS. I was also using PostCSS for compilation and the code is every similar to what I am using.

Thank you for the great effort.

Update of spacing page on website

I needed a solution for spaces using infima, searching in the official website the page that refers to this section has content with TODO only. This page was created in this repository (#108), but has not yet been added to the site, does the project have any plans to update that page?

Table stripe color should be semi-transparent

This doesn't look right:

I'm also trying to allow users to tweak the site's background color: facebook/docusaurus#5822 and any other color doesn't look right with the table stripes still staying dull-black.

mobile version of navbar dropdown

Motivation

Seems that navbar dropdown isnt supported in mobile yet ?

Component suggestion: URL preview similar to GitBook

Pardon me for opening an issue for this (why not enable discussions in this repo?)

I recently switched from GitBook to Docusaurus, and I love it so far. But there's one thing that I miss from GitBook, the URL previews:

See the "hifi-finance/hifi-protocol" card? That was generated automatically after I pasted the URL in the GitBook editor. It would be super helpful if Infima provided a similar URL preview component.

I've seen the Card component in your docs, but it's not quite the same component. That seems to be tailored for long texts and images, whereas I am referring to URL previews specifically.

Footer logo styling artifically restricts real uses

The max-width specified here doesn't support short & wide logos well. Specifically it looks pretty bad when trying to use the new Meta Open Source logo.

infima/packages/core/styles/components/footer.pcss

Lines 53 to 56 in 1273569

	&__logo {
	margin-top: 1rem;
	max-width: 10rem;
	}

This is then not easy to override inside Docusaurus. The width property you can specify in the logo config isn't respected if greater than 10rem.

You could override with inline style here (https://github.com/facebook/docusaurus/blob/6df379ca6f9510793da73183acc851b653575e6a/packages/docusaurus-theme-classic/src/theme/Footer/Logo/index.tsx#L16-L31), setting maxWidth/Height to the values from the config, or figure out where to drop some global override, but that's starting to feel like just fighting the system

Dark Mode does not follow System theme

Context

• Many websites like Youtube and Github automatically switch to Dark Mode if the system is in Dark Mode, without needing to explicitly switch.
• I noticed that websites built with Infima, including https://infima.dev/docs does not follow this convention.
• I think an auto dark mode by detecting the system settings would be a good minor enhancement to the user experience as most of the OSes now support System wide Dark mode options.

Possible Solution

I saw this Article which seems to be related to detecting the system theme and switching to it using Javascript.

Add support for large-scale displays

See https://css-tricks.com/optimizing-large-scale-displays/

@yangshun WDYT?

SCSS rewrite proposal

Copied from Discord:

I think that for Infima, we should possibly consider moving to something like SCSS instead of postcss.

Why:

• Current setup is highly opinionated, and frowned upon by the postcss core team
• It's not as easy to maintain as it probably could be
• It's difficult to build without adding lots of dependencies out of this repository

Pros:

• More widely supported toolchain, compilers for which are available in many different languages, e.g. sass and node-sass
• Could allow for enhanced treeshaking for projects like mine that use ifm outside Docusaurus.
• Better IDE support potentially

Cons:

• Rewriting of some syntax would be required
• It's a decently big shift

Let me know what y'all think.

Styles appearing differently in production vs. development

We are using Infima with Docusuarus 2 and are seeing styles rendered differently in production vs. development. (This may be more of a Docusaurus issue than Infima issue)

For example, our code block styling in development

vs. production

What might be causing this? Here is a link to our custom.css file
https://github.com/redwoodjs/learn.redwoodjs.com/blob/master/src/css/custom.css

Variables shouldn't use color-mod outside of initial palette generation

I have customized theme where I re-defined root variables for primary/warning/danger/etc to match my colors scheming.

The new variables as used in blockquote (and admonitions, separate but related to this issue) introduce new colors not defined by the base palette, and are hardcoded with color-mod. For someone who has customized their theme with just redefining the base set of colors, this introduces a whole bunch of hardcoded new root variables that also now need to be customized to match.

6 * 2 base colors
--ifm-color-XXX-contrast-background
--ifm-color-XXX-contrast-foreground

3 block quote colors
--ifm-blockquote-base-background
--ifm-blockquote-background-color
--ifm-blockquote-border-color

and 6 new admonition colors
--ifm-alert-background-color-highlight

For a total of 21 new colors that now need to be manually specified, for theming.

Suggestions:

I used the color generator https://docusaurus.io/docs/next/styling-layout#styling-your-site-with-infima initially to generate the primary/success/etc dark/darkest/dark versions of my color palette, so a) could extend that to add the new contrast color mods, so there's at least a tool. I like that less, but its workable.

Second, make a hard rule of not using color-mod outside of generating the base palette. Where its used in admonitions and block-quote make theming difficult as it introduces a bunch of new root variable to override.

Third consider a different approach approach to palette generation. If you are okay with HSL https://caniuse.com/?search=hsl , then could do something like https://blog.maximeheckel.com/posts/the-power-of-composition-with-css-variables/ allowing someone to specify just 6 colors base colors, and have everything composed from those.

Search icon doesn't change color between light/dark mode

The search icon as defined in --ifm-navbar-search-input-icon is uses currentColor:

--ifm-navbar-search-input-icon: url('data:image/svg+xml;utf8,<svg fill="currentColor" ...

However, this does not have the intended effect because currentColor does not get applied on images rendered using url(). This results in the search icon not changing color when switching between light/dark theme (and makes it hard to customize the color more generally).

Perhaps a more flexible approach would be to use an actual SVG in the element, similar to how Docusarus has implemented it on their website:

chevron level on different nesting

reduxjs/redux#3635 (comment)

Actually, the bigger problem there is the chevron is quite visually similar to the one below it, despite them being a different levels:

So, whatever styling is done there should also apply to the expandability indicator.

Add styles for details component

From the discussion: facebook/docusaurus#5749

Currently we reuse the Infima alert class name in Docusaurus, which is too noisy (blue background). There seems to be a few good designs proposed in that thread.

Safari clips product name to “Infi…”

When viewing the live site at https://infima.dev on Safari, the Infima text that appears next to the logo in the navbar__brand anchor is truncated to Infi… at all breakpoints.

Looks like a bug with the display: flex property.

(Works fine on Chrome.)

Plan for more components?

Hey guys. Just stumbled on Infima while working with Docusaurus. Awesome jobs you guys are doing here.

But I have a use case that is rather uncommon and requires form components (Input, switches, etc).

I'm sure there are plans for styling more of these components but I couldn't find them.

Could someone give me some heads up?

Thanks a lot, guys🙏

Sidebar category icon not clickable due to using ::after

The sidebar category icon is using an ::after pseudo-element.

It worked fine until now, but for facebook/docusaurus#5830 I'd like to be able to add a click listener to this icon (otherwise this category couldn't be collapsed: https://deploy-preview-5830--docusaurus-2.netlify.app/docs/next/category/guides/), and eventually add some extra :hover styling to make it clear that the icon can be clicked independently from the text.

We could also allow Docusaurus users to provide their own custom icon if they want to.

Control the rounding of ages in pill, badge and buttons

Can we have a way to control the rounding of the buttons, badge and pills.

Say I want the left of right edge square and the other rounded or both square.

TOC should be allowed to display with @media print

When printing a doc (or sending it to your Kindle) it should be possible to print the table of contents in certain situations.

Hiding the right TOC makes sense in most cases, but not in many others.

It is likely more the responsibility of Docusaurus to decide when a TOC can be printed, not Infima which currently does:

.table-of-contents {
  @media print {
    display: none;
  }
}

https://docusaurus.io/docs/next/markdown-features/toc#inline-table-of-contents

Reported in facebook/docusaurus#8362

lint-staged / stylelint does not catch missing Facebook copyright

When a missing copyright header is not found, yarn workspace infima lint should report an error, but it does not (while other lint rules work)

style: navbar: dark version has incorrect brand hover color

Navbar: dark version has incorrect brand hover color

Better dark mode color palette

Our dark mode background is too dark. While it's fine for the Docusaurus website because the text is relatively sparse, as soon as the text gets dense, it literally hurts my eyes.

Not only is the background too black, but the admonition is too blue as well. The light mode contrast seems so much better.

GitHub and Twitter also have this problem (hence I never read long READMEs on GitHub), but VuePress's palette is very nice:

Images with height attribute set do not preserve aspect ratio

Not sure if this should have gone here or in the Docusaurus repo, but anyway.

while images are given max-width: 100%, their height is unspecified, so any height attribute assigned to an image stretches the image. this issue is seen e.g. on the main Docusaurus site at https://docusaurus.io/docs/advanced/architecture.

A simple fix would be to add height: auto to image tags as well.

Back to main menu => missing font-family

The CSS var does not modify its font:

Use of `background` property to set background color clobbers other background properties

I've run into some trouble customizing a Docusaurus site due to Infima's pattern of specifying the entire background property for elements when it's actually just targeting the background-color.

The specific case I'm bumping against is here, but I did a quick search and see many other instances where the background property is being set to just a color.

Problem: This means any downstream customizing such as setting a background image gets clobbered unnecessarily.

Solution: Unless Infima specifically means to clobber any other background properties, it should just set the background-color when that's all that's being specified.

I'm happy to submit a PR for this, although I'm unsure if this is a change I should make everywhere I find it or just in that one instance. Guidance welcome!

Theme colors do not meet accessibility standards for color contrast

Hi, I'm a very happy user of Docusaurus v2 and Infima (via the classic Docusaurus theme). Unfortunately the default theme colors, including the link text color and the background colors for buttons and badges with white text, don't meet the WCAG minimum color contrast standards. I used the built-in color contrast checking tools in Firefox to confirm this.

I'd love if this project could fix the contrast issues so the documentation generated with it was accessible to a wider range of people!

Restyle admonitions

Refer to original issue - facebook/docusaurus#2930 (I'm unable to move issues across organizations).

Documentation for Spacing

Hey there, thanks for the great work on the library.

Are there plans to add documentation for Spacing, as it is currently marked as TODO, and would the team be open to PRs regarding it?

Unability to navigate collapsed menu without JS

Currently on D2 it's not possible to "navigate" to a collapsed menu without JS enabled.

This is probably not the most impactful enhancement we could make, but I think I read it's a goal to make the site usable without JS (or before js hydration).

We could probably expand a collapsed menu item on :focus / :focus-within

Inconsistent design and incorrect colors in dark mode

there seem to be an inconstancy in use of borders / background colors between dark and light mode

most elements in dark mode use background color
most elements in light mode use border

"most" as there is no consistency,

---

search icon in dark mode doesn't adapt to dark mode

---

header has no borders (shadow) in dark mode, but uses different background color from content

eg, side panel has --ifm-toc-border-color: var(--ifm-color-emphasis-300); for both dark and light mode

---

badges do not adapt text color between dark and light mode

---

shadows are close to invisible in dark mode #187

---

cards use background color in dark mode and border in light

Render better long sidebar category labels?

https://pptr.dev/api/puppeteer.frameaddscripttagoptions

This edge case does not look great, we can probably do better 😅

Missing style for expand/collapse navbar

docosaurus currently implements completely custom design for expanding and collapsing navbar, that should be added in here

Doc sidebar active category not highlighted

infima/packages/core/styles/components/menu.pcss

Line 88 in 8c592e4

background: none !important;

This !important has prevented the category link from being highlighted.

[deleted]

[deleted]

Dark mode Badge text color contrast is bad

Currently the default Text color for badges in dark mode is way too white, which is not good to read:

But i had tried changing the text color to the same the buttons are set now:

which would be the change of [data-theme='dark'] {--ifm-badge-color: var(--ifm-font-color-base-inverse);}, which would look like:

(Note: the Secondary overwrite is still in place for this screenshot)

this is just a small mockup (no testing or PR worthy) change but i think it is way better than just the white it was before

Tested and Screenshots from Linux Manjaro 21.3.0 with Firefox 101.0.1 on KDE Plasma Wayland

---

This issue is related to #192, but about a more specific part of it

Code sample for "active" Button include "outline" classes

Small thing. I was looking through the Button component variations and noticed that the "active" style's code samples include classes present in the "outline" style. For example:

<button class="button button--outline button--active button--primary">
  Primary
</button>

Removing the button--outline class appears to retain the active style, any reason it should be left in there?

Visual testing

With a lot of CSS refactors / polishings under the way, we should find a way to ensure they don't regress. Testing CSS on Infima is much easier than Docusaurus, and also much more vital.

I have taken some inspiration from TypeDoc's visual regression CI. From my discussion with Gerrit, it's supposed to be fairly easy, without app installation / service subscription. The only problem when it's not connected to some external service is there's no way to easily retrieve the testing artifacts.

I wonder if we can:
(a) Connect to an AWS S3/equivalent so we can store the snapshots
(b) Use a GH comment action to post the artifact
(c) Install the reg-suit app which seems promising

We can do our tests exclusively on the /demo page, which should make things a lot easier.

tabs: active tab is missaligned with non active tab

tabs: active tab is missaligned with non active tab

Clickable dropdown not opening

Currently, when attempting to open the clickable dropdowns, no dropdown appears.

Stepper component

Requested on Canny: https://docusaurus.canny.io/feature-requests/p/stepper-component

Would be nice to have a stepper component (like https://mui.com/components/steppers or https://garden.zendesk.com/components/stepper, but more integrated with Docusaurus and its theme) for step-by-step instructions.

I think that makes sense

Grid with breakpoints

Hello!
I would like to use different grid layouts depending on breakpoints, like "col-sm-4 col-md-2".
Is it possible? If not, is it on the roadmap?

content link children does not get primary highlighted ?

When i go to https://redux-starter-kit.js.org/tutorials/basic-tutorial (v1)

Notice that "introducing createAction" is both highlighted. But this is not the case for Docusaurus v2

https://deploy-preview-247--redux-starter-kit-docs.netlify.com/tutorials/basic-tutorial

I notice it's because code css color is always var(--ifm-code-color); I think both should be highlighted ?

Variables with zero-value should include unit

Zero-valued variables should always include a unit to be compatible with min/max/calc functions.
Ex. --ifm-footer-padding-horizontal: 0 set in a default media-query will not work atm. Overriding to 0px fixes it.

navbar width too big

Due to 12f9b90

The increase from 15rem -> 20rem navbar width in small device like iphone 5 made it hard to close the sidebar.

Technically there is no backdrop like in larger device

navbar shouldn't contain the navbar mobile sidebar

We should be able to set different stacking contexts (ie z-index layers) for the navbar and the mobile sidebar.

Not doing so is annoying because we want some elements to be able to cover the navbar (announcementBar shadow, skipToContent)... and yet have the mobile navbar cover those.

I gave it a try in facebook/docusaurus#7940 to increase the announcementBar z-index so that its shadow can be seen on top of the navbar (gives a better sensation of depth and seems the right thing to do)

But this leads to issues on mobile:

• facebook/docusaurus#8173
• facebook/docusaurus#8141

Due to the current inability of having 2 separate stacking contexts, I have to fix the 2 issues above by reverting my change, and removing the announcementBar shadow in favor of a bottom border.

---

We should refactor Infima to allow rendering the navbar and its associated mobile sidebar in 2 separate DOM trees. Ie not having classes such as .navbar.navbar-sidebar--show .navbar-sidebar like we currently have, assuming the sidebar is a child of the navbar.

@yangshun if it were me I'd remove all things related to macro-layout orchestration like fixed/sticky positioning and margins from Infima and only declare these things on the Docusaurus side. Having this in Infima creates DX friction to test the change easily locally and in PRs. I'd rather have Infima focus only on the design system elements and not how elements are displayed inside the app. Any opinion?

Note that if we want to have a Tailwind theme, it's likely to have the same mobile sidebar behavior, animation and positions. I'd rather have this CSS in @docusaurus/theme-common as shared CSS modules so that we can avoid duplicating it in each design system / theme.

Logo not loading in 'Multi-Column' example for footer

URL: https://infima.dev/docs/components/footer
The logo isn't loading and you guys may want to change the "2019" to something more dynamic in all three examples (Simple, Multi-Column and Dark) :)

PS: Logo also affects to the "Dark" section right below