SF.gov Fillout theme

This repo contains code and documentation for managing our Fillout theme.

Build

The stylesheet in the theme directory is built for production with postcss and Tailwind (the same tools used to build SF.gov's stylesheets and React components). This helps us write less CSS (e.g. with nested selectors) and more precisely override Fillout's own CSS, which is also built with Tailwind. To build the stylesheet, run:

npm run build

This creates dist/theme-sfgov.css. Set NODE_ENV=production to enable minification. (This is done automatically in the prepublishOnly script, which is run by npm publish.)

Test

You can test the stylesheet with our Chrome extension. Follow the instructions in that repo to install it, then right-click on the extension icon in Chrome and select Options.

URL

If you're reading this on GitHub or npm, or you don't need to modify the source files and just want to see Fillout forms with this version of the CSS, select "URL" and paste this URL into the text field:

https://unpkg.com/@sfgov/fillout@<version>/dist/theme-sfgov.css

...where <version> is a published version identifier or npm tag. For instance, to see version 0.0.6 of the CSS, you would paste:

https://unpkg.com/@sfgov/fillout@0.0.6/dist/theme-sfgov.css

Then, navigate to any Fillout form and toggle the "CSS" overlay in the tab or frame so that it turns green and says "CSS: custom". From this point on, every Fillout form will have its custom CSS replaced by the stylesheet at that URL.

If you change the URL in the extension options, the styles will update automatically. Click the "CSS: custom" toggle at any time to switch back to the CSS of the form's selected theme.

Local CSS

If you're working on the stylesheets in this repo, select "Local CSS" and paste the full path to dist/theme-sfgov.css in the text field, which you can get with:

realpath dist/theme-sfgov.css

Make sure to also check the "Live reload" checkbox so that changes to the file will be applied automatically.

Next, navigate to any Fillout form and toggle the "CSS" overlay in the tab or frame so that it turns green and says "CSS: custom". From that point on, the form styles should update automatically whenever you rebuild the CSS. This pairs nicely with watch mode, which will rebuild whenever source or config files change:

npm run watch

Click the "CSS: custom" toggle at any time to switch back to the CSS of the form's selected theme.

Deploy

We "deploy" the CSS by manually copying and pasting it into the custom CSS field in Fillout's advanced designer.

1. Navigate to the edit view of a Fillout form that uses the default SF.gov theme, such as the kitchen sink form

2. Click the 🖌️ Theme button in the top left of the editor view

3. Click the Advanced designer button at the bottom of the left hand panel

4. Under "Custom CSS", click the Edit CSS button

5. Copy the contents of dist/theme-sfgov.css:

   # in macOS terminal
   cat dist/theme-sfgov.css | pbcopy

6. Paste the CSS into the modal CSS editor

7. Click Apply CSS to save the styles

8. Click the Publish button in the top right to publish the form and the theme.