All posts

Tools

Make your hackathon demo easier to use with a keyboard

Check labels, focus, page structure and error messages so more people can try the project without a live explanation.

HackHoster Team · · 4 min read

Smoked glass channels joining through a copper connector and charcoal ring
Illustration: HackHoster (AI-assisted), original artwork

At a glance

  • Use real buttons, links and labels for the actions people need.
  • Test the full journey with a keyboard and visible focus.
  • Explain errors near the affected input and preserve entered work.
  • Include accessible instructions and a text alternative to video.

Practical guidance from HackHoster. Sources and illustration credits accompany the article. Publishing standards and corrections.

A usable hackathon demo should let someone understand the task, reach the controls and recover from mistakes. Start with semantic page structure, visible labels and a complete keyboard journey. Accessibility belongs in the working prototype because it affects whether a person can evaluate your idea at all.

You do not need to claim that a short checklist proves full accessibility. It does not. The checks below are a practical first pass for a small web application, informed by W3C tutorials. They help you find concrete barriers while leaving room for deeper testing with people and assistive technology.

Conceptual illustration of separate components connected into a reliable path
Illustration: HackHoster (AI-assisted), original artwork

Start with the task, not the decoration

Write down the main journey as actions: open the project, choose a sample, edit a field, run the tool and save the result. Identify every control needed to complete it. Decorative imagery can support the explanation, but the essential task should remain understandable as text. Do not hide the only instruction inside a screenshot.

Use headings to describe the organization of the page. A screen full of large text is not necessarily structured. Give each major section a useful heading and keep its content together. In a checklist generator, input, review and export are meaningful stages. Repeated headings called information tell the reader much less.

Choose controls that already have meaning

Use a button for an action and a link for navigation. Native controls give the browser a useful starting point for keyboard and accessibility behavior. A clickable rectangle assembled from unrelated elements makes you responsible for recreating those behaviors correctly, which is usually unnecessary for a small prototype.

Give each input a visible label. A placeholder can offer an example, but it disappears during typing and should not carry the whole instruction. Put format guidance near the field. If a date must use a particular format, say so before the user submits it. Group related options under a clear shared description.

Follow the journey without a mouse

Put the pointer aside and start with the keyboard. Move through the page, activate the main controls and return from dialogs. You should be able to tell which element has focus and whether the order follows the task. Make notes whenever a control cannot be reached or the next position is surprising.

Test the result after actions, not just the initial page. Open a menu, trigger an error and finish a request. Can the user continue from the current focus position? If a dialog closes, do they return to a sensible place? A working initial tab order can still lead into a trap after the interface changes.

If a feature requires a mouse to complete the main task, it needs attention before the demonstration is ready for everyone who uses a keyboard.

Treat error messages as instructions

A red border is not a complete explanation. Say what went wrong, identify the field and describe an achievable correction. Keep the user's existing work when possible. For a missing project title, a short message near the title field is more useful than a generic failure notice at the top of the page.

Check that errors remain understandable without color. A loading state should also communicate progress in words when it affects the task. Avoid replacing the entire page with an unexplained animation. After success, make the outcome identifiable: the file is ready, the draft is saved or the review still needs confirmation.

Check contrast and small screens

Try the demo on a narrow viewport and with larger text. Important controls should remain visible and content should not require sideways scrolling for ordinary reading. Long names and unexpected values can reveal layout problems that your short sample labels conceal. Test at least one realistic long value rather than only empty screens.

Check foreground and background contrast in the actual states people will use, including disabled, focused and selected controls. An automated tool can help find some problems, but it cannot tell you whether the wording makes sense or whether the journey is coherent. Combine technical checks with someone actually attempting the task.

Make the explanation accessible too

If you submit a video, add accurate captions and a text walkthrough. Describe meaningful visual changes in the narration instead of saying click here without context. Make the README useful for someone who does not watch the recording. Explain the sample input and the result they should expect to see.

Keep a short record of the checks you ran and the limitations you know about. Avoid labeling a project fully accessible after a quick scan. Specific evidence is more useful: the main journey was tested with a keyboard, labels were checked and a remaining chart still needs an equivalent table. Read the demo testing guide for a broader rehearsal.

A short exercise to try

Keep a barrier log during the keyboard rehearsal. Record the step, the expected action and the observed obstacle, such as focus disappearing when a result arrives. Assign each obstacle a concrete fix and retest the full path after the change. A small log keeps the discussion about behavior instead of whether the page looks accessible. If you cannot resolve a barrier before the deadline, describe it in the known limitations and provide another usable way to inspect the relevant result.

Use the current challenge brief to choose a workflow for these checks, and confirm the published deadline before preparing your final submission.

Sources