{
  "title": "Date and time picker",
  "path": "/components/date-picker",
  "url": "https://design.werklist.com/components/date-picker",
  "text": "https://design.werklist.com/agent/components/date-picker",
  "summary": "Fields for a date or a time that accept typing and open a calendar or a list of times.",
  "version": "2.1.2",
  "kind": "component",
  "name": "DatePicker",
  "purpose": "Takes a calendar day or a time of day, typed or picked from a month calendar or a list of times.",
  "use": [
    "One day: a start date, a passport expiry, an interview",
    "A period, as two fields labelled Start and End",
    "A time of day, with the time field"
  ],
  "avoid": [
    "A date shown in figures only, such as 09/10/2026",
    "A year in two digits",
    "A calendar as the only way to reach a day far from today"
  ],
  "anatomy": [
    {
      "part": "Field",
      "measure": "a text field with a 32 px icon button at its end, named Choose date, holding a 16 px calendar icon",
      "token": "--input-border"
    },
    {
      "part": "Calendar",
      "measure": "284 px wide, narrower in a small window, padding 12 px, corner radius 12 px",
      "token": "--glass-fill-raised"
    },
    {
      "part": "Calendar shadow",
      "measure": "the raised shadow, with a top highlight and a fine ring in dark",
      "token": "--glass-shadow-raised"
    },
    {
      "part": "Header",
      "measure": "the month and the year, 14 px on 20 px, weight 700, between 32 px buttons for the previous and the next month",
      "token": "--text"
    },
    {
      "part": "Weekday row",
      "measure": "short day names in the reader's language, 11 px on 16 px, weight 500, 4 px above the days, Monday first",
      "token": "--text-muted"
    },
    {
      "part": "Day",
      "measure": "36 px high, as wide as its column, corner radius 8 px, 14 px aligned figures, in seven columns 2 px apart",
      "token": "--text"
    },
    {
      "part": "Day under the pointer",
      "measure": "a light fill",
      "token": "--glass-fill-hover"
    },
    {
      "part": "Day in focus",
      "measure": "a 2 px ring of the brand blue at 40 percent",
      "token": "--brand-blue"
    },
    {
      "part": "Chosen day",
      "measure": "the brand fill with white figures at weight 700",
      "token": "--brand-true"
    },
    {
      "part": "Today",
      "measure": "a 4 px dot in the brand colour, 4 px above the bottom of the day, hidden on the chosen day",
      "token": "--brand-true"
    },
    {
      "part": "Day that cannot be chosen",
      "measure": "faded to 30 percent, with aria-disabled"
    },
    {
      "part": "Days of other months",
      "measure": "left blank"
    },
    {
      "part": "Time list",
      "measure": "slots every 30 minutes from 08:00 to 21:00, under the headings Morning, Afternoon and Evening in 11 px on 16 px, with the rows of the combobox",
      "token": "--text"
    }
  ],
  "sizes": [
    {
      "name": "md",
      "height": "44 px"
    },
    {
      "name": "lg",
      "height": "48 px"
    }
  ],
  "states": [
    {
      "name": "Field states",
      "change": "As the text field, with no hover state",
      "tokens": [
        "--input-border",
        "--brand-blue",
        "--error"
      ]
    },
    {
      "name": "A date the field cannot read",
      "change": "The text is kept, and the error gives an example: Enter a date like 28 Sep 2026.",
      "tokens": [
        "--error"
      ]
    },
    {
      "name": "Touch screen",
      "change": "The device's own date or time picker takes the place of the calendar and the list"
    }
  ],
  "keys": [
    {
      "key": "Left and Right arrows",
      "action": "Previous and next day"
    },
    {
      "key": "Up and Down arrows",
      "action": "Same day of the previous and next week"
    },
    {
      "key": "Home and End",
      "action": "First and last day of the week"
    },
    {
      "key": "Page Up and Page Down",
      "action": "Previous and next month"
    },
    {
      "key": "Shift+Page Up and Shift+Page Down",
      "action": "Previous and next year"
    },
    {
      "key": "Enter or Space",
      "action": "Chooses the day and closes"
    },
    {
      "key": "Escape",
      "action": "Closes without a change. Focus returns to the calendar button"
    },
    {
      "key": "Tab",
      "action": "Moves between the month buttons and the grid. One day is in the tab order"
    }
  ],
  "accessibility": [
    "The calendar is a dialog with aria-modal=\"true\", named after the field label",
    "The month is a grid. Each day is a button named with its full date",
    "aria-selected=\"true\" on the chosen day, and aria-current=\"date\" on today",
    "The month heading is announced when it changes",
    "With reduced motion the calendar only fades, and months do not slide"
  ],
  "content": [
    "Display: the day, the short month and the full year in the reader's language, such as 28 Sep 2026",
    "Input: the day first with dots, slashes or spaces, the month by name, or year, month and day in that order. The year is written in full",
    "Clock: 24 hour, or 12 hour when the person's settings say so",
    "Time zone: named in the hint when readers in more than one zone see the value"
  ],
  "tokens": [
    "--glass-fill-input",
    "--input-border",
    "--glass-fill-raised",
    "--glass-shadow-raised",
    "--glass-fill-hover",
    "--brand-blue",
    "--brand-true",
    "--on-brand",
    "--text",
    "--text-muted",
    "--radius-lg",
    "--radius-xl",
    "--space-1",
    "--space-3",
    "--layer-popover"
  ],
  "rules": [
    "A date without a time is a calendar day, stored and shown without a time zone",
    "A period is two fields. The End calendar opens on the month of the start and offers no earlier day",
    "Slots are 30 minutes apart, or 15 when the task needs it"
  ]
}