form-jekyll

form-jekyll is a Jekyll theme that lets you easily build a prototype of an SF.GOV form in a YAML file. Right now, it lets you add:

Multiple field types
Custom error messages
Custom input widths, tied to the maxlength attribute
Conditionals for radio buttons, checkboxes, and text fields
"Less than" or "greater than" conditionals for number fields
Markdown-formatted content

Since YAML is easy to read, non-technical colleagues can easily give feedback on form design and content inside a GitHub pull request. And because GitHub Pages uses Jekyll, you can easily deploy a form to a webpage and send the link to external stakeholders.

Project goals

Designers can prototype, comment, and iterate on forms as easily as they might a Google Doc.
Designers can easily give external stakeholders a realistic preview of how a form will work.

Demo

https://form-jekyll.netlify.com/

Getting started

First, set up Jekyll, and run bundle install to install the Gemfile.

Then, set up your development server with bundle exec jekyll serve --watch.

Creating a new form

Create a new Jekyll project
Add form-jekyll to the Gemfile
Add a YAML file named after your form to the _data directory. (If the directory doesn't exist, create it.)

Add an HTML file to the root directory with the front matter:

---
title: [Title of form]
form: [name of YAML file, without the extension]
---

Now it's time to start writing your form! Here's an example of what your YAML file might look like.

- title: Page Title
  fields:
  - label: Name

  - label: Phone number
    type: phone
    error: You need to enter a valid phone number.

  - label: Do you have an email address?
    type: radio
    options:
    - label: Yes
      shows: email-field

    - label: No
      hides: email-field

  - group: email-field
    fields:
    - label: Enter your email address here
      type: email

  - label: How did you hear about us?
    optional: true

(Scroll down for a full list of field properties.)

Directory structure

_includes/fields: partials for all field types. (If you want to add a field type, place it here.)
_includes/elements: partials for standard HTML elements (like labels and help text)
_includes/sfgov: partials for SF.gov-specific patterns
_includes/pages: Standard pages for the form (like preview and confirmation pages)

Previewing prototypes

Visiting your development server (usually localhost:4000) will show the "Choose a prototype" page. Click on one of the forms to preview it.

The admin panel

Since you're building a prototype, you're also able to preview your forms at different levels of abstraction: you can see all pages on the same screen, view annotations from the form's creator, or toggle all conditionally hidden fields.

To toggle these settings, press Command + Option + . or Control + Option + . when viewing a prototype.

Comments

Clicking the admin panel will also toggle Hypothes.is, a plug-in that lets external stakeholders annotate webpages with copyedits or general feedback. (You need to register with Hypothesis in order to leave comments.)

Field properties

Property name	Description	Expected format
`title`	The title of the current page	Plain text
`fields`	The fields within a page or `group`.	A nested list of fields
`label`	The field's label	Plain text
`helptext`	The field's help text	Markdown
`type`	The input type. For a full list of fields, see the file names in `_includes/fields.`	Plain text
`options`	The possible answers for `radio`, `checkbox`, and `select` fields.	A list of options
`checked`	Determines whether a radio or checkbox option should be checked by default.	`yes` / `no`
`optional`	Determines whether a field is optional	`yes` / `no`
`other`	Determines whether a set of radio buttons or checkboxes has an "Other" option	`true`
`error`	The custom error message that should display if the field is invalid or blank.	Plain text
`shows`	The name of the `group` that should be conditionally shown if this field is checked.	The name of a `group`
`if`	The logic that will trigger a conditional for a free-text field.	Plain text or a number (for exact matches) `<X` to match all numbers less than X (e.g. `<49`) `>X` to match all numbers greater than X (e.g. `>49`)
`level`	The header level for `header` fields. For example, `level: 1` will produce an H1.	A number between `1` and `5`
`group`	The name of the group of fields you wish to conditionally show or hide.	Plain text
`size`	The vertical height of a textarea	`small`, `medium` or `large`
`unit`	The desired units of a number field (e.g. "yards", "liters", "days")	Plain text
`url`	The URL of a link.	Plain text
`maxlength`	The maximum character length of a number or text field.	A number between `1` and `15`
`address-fields`	The inputs to show in an address fields. (All inputs are visible by default.)	A nested list containing `street`, `city`, `state` and `zip`
`annotation`	A note that you'd like to append to this field in your prototype. (When viewing a prototype, you can toggle annotations in the admin panel.)	Markdown
`hidden`	If set to `yes`, this field won't be visible to the user. (When viewing a prototype, you can toggle hidden fields in the admin panel.)	`yes` / `no`

SFDigitalServices/form-jekyll