Theming Semantic UI with create-react-app

Semantic UI’s default styling is great, but it’s not the end-all/be-all of web design. Semantic’s versatility in terms of build options is great for quickly deploying something beautiful, but it’s confusing when you want to customize it with your own fonts/colors/etc.

This blog post contains the recipe I used for going from default Semantic UI settings to a “Hello World” page using Arial instead of Lato as the site-wide font- kind of a “Hello World” for styling. It assumes you already have experience deploying React apps with create-react-app and have some familiarity with Semantic UI.

Create the React App

Run create-react-app to build your basic front-end. Nothing unusual here.

Install Gulp

Gulp is Semantic UI’s task runner. In layman’s terms: when you customize your Semantic Build, Gulp will merge and minify it into semantic.min.css, etc. so your app can refer to a single file for custom styling or other tweaks.

Run npm install gulp to install it.

Install Semantic UI

Semantic has various configurations of how to do this, depending on your level of customization.

Run npm install semantic-ui-react to use Semantic as a library of React components.

Run npm install semantic-ui to deploy a fully-customizable Semantic build. The docs suggest doing a yarn add instead of npm install, but Yarn failed to actually install Semantic (it’s a known issue right now).

Choose Express Setup when Semantic prompts you. The create-react-app build right now requires you to install Semantic UI in your project’s example-app/src/ directory (as opposed to your root example-app/ directory, which is the Automatic install setting).

Semantic UI needs to live inside example-app/src/semantic/ because your create-react-app instance won’t have permission to look outside the example-app/src/ directory.

Build Your Semantic Library

Run gulp build inside example-app/src/semantic/ to create your default Semantic install.

Run gulp watch inside example-app/src/semantic/ to have Gulp automatically update Semantic when you make changes to your theme.

Customize your Site theme

Now we’re operating within example-app/src/semantic/. The docs can get confusing because Semantic UI has its own /src/ directory as well. For brevity at this point, keep in mind when I refer to /semantic/src/ I’m talking about example-app/src/semantic/src.

You can customize the site theme at src/site/. This can be confusing because you’d think your theming should take place in src/themes/ cuz logic.

Without diving down a rabbit hole about theming options, I choose to customize the site theme because it has the final say on how your CSS comes out. The site theme overrides everything that comes before it.

Inside /site/globals/ you’ll find a file called site.variables, which is where we’ll finally change some base styles.

Drop in this snippet to change the theme font to Arial:

@emSize: 13px;
@fontSize: 13px;
@fontName: 'Arial';

Import Semantic UI CSS

Within your app’s src/index.js file, add the following import line:

import './semantic/dist/semantic.min.css';

This is the minified CSS file your Gulp task runner will build whenever you make changes to your site theme.

Errors? Outta Luck.

Don’t expect any indication you’ve done something wrong when editing your Semantic UI theme. If it doesn’t like your CSS for any reason, Semantic will default back to its original settings.

Accessibility is for Everyone

People often leave Accessibility in design and coding to people with less important problems and more time on their hands. I think this comes from misunderstanding what it means to make an app or website accessible in the first place. And I find it kind of ironic that the term Accessibility itself is inaccessible because it’s jargon.

Think of your app. You made it, no one’s used it before. If people struggle to use your app, it’s more likely that you’re inconsiderate than that your user is incompetent. Developers get paid to make apps normal people (let’s call them Muggles) can actually use.

When I came into software dev training at the Flatiron School, I imagined the best code was brief and cryptic, like haiku for computers. But we don’t only write code for computers- we write it for other coders. Please enjoy my code haiku below though:

function x(y,z){
b = y.map((a) => (
z.//I give up)} 

Writing for other coders creates accountability for otherwise rushed decisions, resulting in a better end product. You know, like something that makes sense after the bathroom break too…

But what about writing and designing apps for other people, like just generally? Like, what happens when we start to consider people with common disabilities we don’t personally have? How do we even? Can we even?


Designing for situational disabilities

Starting with broad strokes is a good way to begin designing for people who are not me. As in, people who would pay a developer for work. We can start with people on their phones, as opposed to my fancy MacBook Pro:

Phone is too big, can’t reach the button

Clickable elements need to be within the average thumb’s distance.

Diagram of touchable points on an iPhone

Spotty reception or slow connection

Avoid bloating page content. For instance, don’t use auto-playing video content on mobile views.


We don’t all see the same

Vision is the first thing I think of when I hear about Accessibility.

Some people don’t see webpages

They use screen readers instead. Screen readers speak web pages aloud. They navigate pages based on HTML tags and ARIA attributes, which are some of the easiest code to neglect. Describing the sections of a page for screen readers is like describing your functions. It leaves less room for sloppy or arbitrary decisions.

Some people navigate with the Tab key

A very common offense here is using CSS to disable outlines on focused elements. Without the outline, people who navigate by keyboard won’t know where they are.

As a side note, paying attention to usability tends to produce better style overall


We’re all on the spectrum

That’s what makes it a spectrum. Reading about Accessibility for people on the outer edges of the autism spectrum, feels like a primer on UX. I got the sense that the main difference between people on the far end of the spectrum and myself is their sensitivity to things I pretend don’t irritate me. For instance the white paper above mentions these items in the context of corporate events, but they apply to designing user experiences in general:

Limit loud/unpredictable noise, motion, and other stimuli

Blinking or flashing text fields in horrible colors are the classic no-no from 90’s-era websites. Then MySpace tuned us in to the idea that empty (“white”) space is more than a suggestion.

Animations on modern websites are usually best to use in response to user actions, rather than trying to grab attention.

Don’t create unpredictable events

Pop-ups are the classic case of an unwelcome, unpredictable event happening during your user experience. After popup blockers became effective, designers started using in-window popups instead of new-window popups. They came up with fancy names to describe them too, so that muggles wouldn’t know how to complain about them en masse:

  • “Modal” windows set to pop up without user action, obscuring active content. These often pack a double-whammy for people who browse the web with keyboards and screen readers (see this example) because they don’t include accessible ways of closing the popup- even for people with perfect vision.
  • “Interstitial” popups- a fancy word for the kind of ad that takes over your entire screen for 5…4…3…2…1… before you can access content. These are a huge turnoff to users, and trigger an SEO penalty on mobile.

These often come with a shaming element to complete the arm-twist:

Intrusive popup "modal"
Please just don’t even

Use simple language

Please spare your reader’s inexplicably diminishing cognitive faculties by saving the long words for your next angry email.

Only use jargon and complex language where necessary. Big words crowd out the point, and cause users to skim or go elsewhere.


Last thing: divide content on the 3’s if possible. I’ll tend to write helper function if I’m writing the same code more than twice. In design you can use visual cues like the HR element above, or hide the additional content behind tabs or in (jargon alert) an accordion pattern.

Wow such clever!
Mark Bello

Mark Bello