form-jekyll

Goals of this tool

  • 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.

What is it?

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.

Example

- 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

Demo

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

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
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
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)
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

Local development